MCPA MuleSoft Certified Platform Architect Level 1 – Designing Effective APIs

1. API Design

Hi. Welcome to the new section. In this course. In this section, we will be discussing how to design effective APIs. And the objectives of this section are we will understand the importance of the contract first APA design and the RAML fragments. And then we will also move on and understand how to do APA versioning and where to expose what elements of an API version. And we will also learn about the data models, like the Enterprise data model and the bounded context data models.

And we will also learn how to choose between the Enterprise data model and bounded context data model. Then we will learn how to actually design our system APIs properly to abstract them from the backend systems. Then we will move on and we will do some Http based asynchronous execution of API invocations and also see how to apply caching to meet some of the NFR, although we have already seen this asynchronous execution and the Http caching policies in the previous section.

Here we will discuss bit more about this. In the last, we will see how the item potent Http methods work and what are the Http native support for the optimistic concurrency in the Http world. All right, so without wasting any time, let us move on and understand the first part, which is about the APA design on any point platform. Okay, so let’s see about the APA design with any point platform and the Ramlsoft actually, like, they do a lot of promotions, right? They always again, one of the point which they promote is the APA specification driven design, meaning the contract first APA design.

So what MuleSoft suggests is we have to start by creating the API specification, ideally in the form of our ML definition. And then we have to simulate the interaction with the API based on that particular API specification. And next thing is, after doing these two, we have to gather feedback from the potential future API consumers as fast as possible. And also we have to publish documentation and API related assets, including the RAML definition of the API only. Then we have to start the implementation of the APA. Okay? So until the first four, which we discussed are done and properly established, user does not recommend.

To start the APA implementation, we have to first start the APA specification as a RAML or any other supported specification mechanism. Then simulate the interactions with the APA specification, gather the feedback from the potential future APA consumers, publish the documentation and all the related assets to the exchange only then start the APA implementation. So this is the approach that has been followed even by us so far in the course in all the previous sections, which is good. Now let us see what are the other things supported by the end point platform in the aspect of APA specifications? So what other APA specifications are supported? The first one, like you know, is the RAML definition. So the Ramble definitions are the first class support in all relevant components.

So with respect to API, every single RAML component or the variety of it are supported by the endpoint platform. Then the second specification supported is Open API, also called as OAS. If you have seen before Open API spec or Swagger So these Open API documents are also supported. So we can import or export in the Any Point Design Center such Open API specifications, or we can also import in the Exchange Any Point Exchange as well. And the third API specification is visual documents. WSDL which are soap. Right. So we can import such documents in the Any Point Exchange. Now, let us understand about identifying and publishing reusable RAML patterns. It is not only entire APIs that can be reused in an application network. Okay? If an API specification is defined in RAML, then it is likely that it makes use of concepts that are reusable in other contexts.

These reusable parts of a Ramble definition are called the Ramble fragments. We already saw this definition before. Right? So what are the Ramble fragments? Are the small pieces of the Ramble correct. So the Ramble fragments define aspects of the interface between an APA client and an AP implementation of the APA in the quotient. So they are like partial interface definitions that can be mixed in to a complete RAML definition. So all such smaller Rammell fragments will be composed and they form a full complete Rammel definition with the support of the C 418.

So what we can do is you can isolate these and the other Rammell fragments from the APIs that are identified in your organization project. Okay? So again, we discussed this in the previous sections, where these Ramble fragment creations can be owned by the C four E and they can come up with all the reusable fragments. So, as we discussed, some of them are like the RAML Security scheme definitions for History, P, Basic Authentication and VOA 20. Some other fragments are the RAML Library, containing resource types to support collections of items, and the RAML Library also containing resource types as well as pride, like we used in some of the lectures in the previous section to support Asynchronous processing of APA invocations with polling, etc.

And RAML trites alone as well, without the library for the APA policies recommended at the organization of yours, like the client ID enforcement slabs and non slabs, rate limiting, throttling and spike control, etc. You can have tried saving for such kind of policies or NFR. So these Ramble fragments are represented in the Any Point platform in two places, like we have seen before. One is the Any Point Design center and the Any Point Exchange set.

So the fragments can be designed in the Design Center, just like the actual RAML, and they can also be published to the Any Point Exchange. So this makes them discoverable and reusable within the application network. So you can see a sample snapshot here where what kind of different fragments are there on the exchange and how they can be discoverable? All right, so this lecture is more about just a kind of revision to understand what all things as part of the APA design are covered so far in the course, as well as to make you understand that whatever we did so far as per the use of proposal or recommendation. Okay, so let us move on to the next lecture, which is about the versioning of the APIs. All right, happy learning.

2. Versioning APIs

Hi. Roll up your sleeves. As in this lecture, we are going to understand about the versioning of APIs and we will go in depth to see how can we version various kinds of APIs and where all versioning will come into the picture. Okay? So let us first understand the strategy for APA versions on the Any Point platform. So again, what New Soft recommends is we have to follow a split strategy on versioning APIs. Number one, try very hard to make all changes to APS backward compatible, okay? You have to make sure that they are all backward compatible. And number two, assume that incompatible changes will be needed at any point, right? And hence version your repays from the starting don’t start versioning after going ahead with some implementation or in the middle of the project, you have to always assume that incompatible changes will be needed at some point.

So version your API is from the starting only. Okay? So an API versioning approach is visible throughout the application network. So therefore you have to get the standardized ones by the C four E. So what do we mean by their visible throughout the application network? So, on Any Point platform, the version of an API is visible in multiple places. So the first one is like at the URL of the Any Point API endpoint. In the RAML definition of the API like the version and the base Uri in the Any point exchange entry, okay, the asset will be published to Any Point exchange. There is something called APA version, asset version and the APA instances and also in the API manager as well in the APA manager APA instance level, the APA version and the asset version implementation URL, consumer endpoint. So these are all multiple places where the version is visible on the Any Point platform and in the application network.

Okay? So that is why we have to make sure that we need to get the standard guidelines from the C four E. Because otherwise what happens is as is visible across the platform, if different teams or lobbyists follow different approach, then it shows the misalignment across the organization. So this should be therefore standardized by the C four E. Now, let us understand the semantic version of APIs on Any Point platform. So what is semantic versioning which means like the English meaning or definition, say semantic is a meaningful versioning. Okay? So use this semantic versioning with the format like major, minor and patch version numbers for the API, like general notation, right? A major, dot, minor, dot, patch. Okay? So like we see one, dot, zero, et cetera. So what do they represent if you do not know already this approach. So the major part of the version semantic versioning says that the major versions introduce backward incompatible changes in the structure of the API that require API clients to adapt. Okay? Meaning API client has to change.

So when you are changing the major version which means the first part of your version number, then you are indirectly conveying that there is a major change and the API is not backward compatible. Meaning the existing clients who are already using the API will break if they consume that particular measure version. If they change to measure version. So they also need to change the client side. Also they have to change the code. Okay? It’s such a big change. Now this middle part, which is minor version, says that the minor versions introduce backward compatible changes to the API that do not require APA claims to change, unless the APA claims wants to take advantage of the newly introduced changes. Okay? So which means the minor versions, if they change, says that there is a new feature or something that has come in the API.

But if you consume by consuming this latest version, like say from 10 to if you move to one 10, your current consumption will not break. Your current application on the client side will not break. But you can’t use the new feature also same time. All right, whatever is the new featured version is 10. The clients cannot use as is. But if you want to use, then only you can change the code on your side, which is the consumer side. But if you don’t want to consume and proceed, you can still use the one 10 latest version, but it won’t break any of your code, but only that your new features can’t be leveraged. If you want to leverage, then only whenever you have time you can change. Okay, so that is the nature of the minor. If you change the minor in the middle part of the versioning, the minor version, it says that, okay, it’s a non breakable change.

Okay? It’s a backward compatible meaning major is backward incompatible. Now, the last, when the patch version, the last known stands for patch version, it says that the patch versions introduce small fully backward compatible fixes such as documentation changes or very minor changes documentation, some non breakable field edition, et cetera, et cetera. Okay? So if the semantic versioning is followed, then version say one two three of an API is a perfect stand in for version one five. And so all API clients that have previously used version one one five can be made to use version one three instead without having to made aware of the transition. Why? Because from one one five, what’s changed in one two three is only the minor and the patch version.

The first one, which is one is still same, only the one five is changed to two three, which means the minor and patch levels are changed. As we know, both minor and patch level are backward compatible. So the client need not even aware or even if they are there, they do not change their code. So for this reason, typically only the major version of an API is made visible to the APA clients. Why? Because the client should not get unnecessary tension. Okay? We understand these definitions of the versioning. Okay? All right, so we may think changing minor and patch versions won’t impact client, all right? But all the consumers may not be aware of our notation, correct? So to reduce the tension in them by suddenly if they see one day 1100 hundred and five becoming 103, they might get an upset or some unnecessary friction saying okay, there is a new version, we were not made aware.

What if our application breaks? Or they may assume things which are issue on their side might be happening because of this change issue could be on the client side, but they will say no, you change the something in the version one or two or three. So adrift is breaking. So for that reason only the major version of an API is generally made visible to the APA clients so that they need to be concerned only if they see the change in the major version. Okay? You have to remember this particular thing as it is important in your platform architect exam. So by the way, you will get some two to three questions as well and specifically with respect to versioning.

So the questions will be like version has been changed from just like we discussed one one five to one two three. Should the APA clients be concerned? How do you communicate? Should you immediately send an email to them? Should they really change their code? Et cetera, et cetera. So you try to choose the right option based on the question. So if the minor end of the patch versions change then they need not be worried. Their clients can just consume as is and they can adapt to the latest changes whenever they want. If the major versions change, then if they have to go and change the code on the APA client side. Okay? So this means that only the major version of the API should be visible in the places where we discuss the version will be reflected, right? Like the URL of the API endpoint. The RAML definition of the API in both version as well as the base Uri the any point exchange asset for the API in API version the any point API manager entry for an API instance in the APA version implementation URL as well as the consumer endpoint. So by contrast, the fully semantic version is visible in the any point exchange entry.

Okay? For the API version and API instances. All right? So the major version part which we discussed is in the above points we discussed the above places where all we saw there only the major version is reflected. But in some places which are in the platform, not to the consumers or the APA clients, the full version is reflected in the exchange. There is a field called set version and the AP instances there the full version is shown also any point APA manager entry of an API instance also has a set version. Even there, the full semantic version is visible. Why? This is because the Any Point Exchange entry of the type Rest API also stores the Rest definition itself.

Okay? So the any point API Manager entry for an API instance will depend on that API specification for the definition of APA policies that apply on the selected combination of API resources and APA methods. So, because of this Rammel definition link in the API entry, APA Exchange and the APA Managers, the full version has been reflected there because to make sure which asset of the Ram specification they are linked to to show the multi version compatibility. All right, now let us go a bit deeper and understand the versioning of the APA and the point URLs. Okay? So like, in what part of a URL should the APA version come more visible? So generally the practice, again you will soft suggest is that encode the version just in the URL path. Okay? For example, you are seeing a sample URL in front of you, like http slash hostname cloud Hub IO whatever, slash V one.

Right? So there in the URL we are showing that the version of this particular API is a V one version one card. So this requires DNS lookup of the hostname that XYZ Cloud Hub IO to resolve to an APA implementation, because every URL has to resolve, right? Even for our credit sales order expand sales order hyphen APA we deployed on the runtime a while back in the other section lectures. So there when we tested from postman, we took that AP implementation runtime Manager URL, okay? So that has to be taken. So the DNS name should be resolved to an AP implementation that supports all versions of the API, including the future measure versions.

Okay? So alternatively, all API invocations must be routed onto the server side of the API implementation that support the requested version. Okay? Meaning what I’m trying to say here is we get only that host name, the Xvij Cloud Hub dot IO from the end Time Manager. It does not give any out of the box feature to have V one, V two. Then how will that request be routed to the correct resource? Or how do we know? Okay, if we have two applications running, one, you may think or call it as a version one application and another as version two.

Or within an application, there are two resources. One is a version one resource and one is version two resource. How do we generally root it? So the AP implications must be routed on the server side of the AP implementation that supports the requested version. There are many ways. One way is there is a support from the Cloud Hub dedicated Load balancer DLB. So you can have URL mapping rules, okay? You can add a URL mapping rule saying, okay, if I get a URL with pattern like okay, slash V one for this application, then send it to this particular runtime application. Okay? So this is one way of doing it. Second way is to have it inside your AB implementation only your name, your resource as v one, V two, Slash, whatever, so that it is part of your resource name and it will go easily to whatever resource. But this is one way of versioning your URL, one recommended way of use of the recommended way of versioning URL. But there are other ways. One or the user for your organization has to weigh between these other approaches as well and decide which one best fits you.

The second approach is encode the versioning just in the host name itself, okay? Not in the URL path, in the host name itself. Like something like the XYZ v one, hyphen cloud hubble typo. So this way it allows the future or major versions of the API to be backed by a different API implementation or the proxy without having to do URL relating and all. Okay? But only disadvantage of this is your version is tightly bound to the host name or the DNS name itself, correct? So you would have to give different DNS and also you have to maintain multiple DNS names b to DLB or your own DNS server and all. So this is on this side, but Pro is you can have pattern. Like one host name is pointed to one API implementation and the host name if it comes v two. In future, you can have a dedicated URL for it like hyphen v two and have it pointed to the another application which is V two application. Okay? It is a different API implementation itself, whereas the first one is the URL path.

The host name or DNS name will be one so that you won’t worry about maintaining multiple DNS servers for that host name. Just the URL path will change like slash, V one, et cetera, which can be managed by different URL mapping rules in the DLV or resource name. Okay? The third way is to encode the version in the host name and the URL path, the combination of both. So like, you’ll have example xyzv one V one again, so this is redundant, but allows the URL path on its own to identify the requested APA version without URL rewriting. So it allows the same AP implementation to expose endpoints for more than one major version. Okay, so you may think, why this much complexity? Why not go with one? Yes, as an architect, we have to weigh between Pros and cons because you know, right, different organizations or projects have different needs. For some organizations, having multiple DNS names is not at all an issue. So they can go with the second approach by versioning inside the host name. But for some, they cannot have or maintain multiple host names or DNS names because of this version change.

They want to have something like one API Mycompany. com, okay? APA Mycompany. com or API mycompany. com, something like that. And they want to only maintain three versions in the URL path so they can go for that. So one has to be discussed within the teams with C four, et cetera. And come up with a proper versioning in the endpoint Uri. Okay? Now let us move on and understand some of the important guidelines of API versioning. Okay? The C four E team actually it should define the guidelines in some or other manner what we are going to discuss now. Okay, so this is what we are going to discuss are general good patterns in the mule software which C four E or any C four in any company should be doing, but not only limited to this, these are basic but they can be added more as per the organizational need or enterprise needs. So the following APA versioning guidelines are fully supported by the way by the Endpoint platform what we are going to discuss now.

So one guideline number one is only expose major APA versions as v one, V two, et cetera. In RAML definition, APA endpoint URL and API any point APA Manager entries in the APA version implementation URL consumer URL, okay, only exposed major APA versions, never expose pullman in the API endpoint URL expose the major APA version only, okay? Be it be in the host name, DNS name or in the URL path. Whatever you pick it as we discussed in the URL versioning in the previous slide, always mention only the measure version. Okay? So it requires future measure versions to either be implemented in the same APA implementation or to root AP invocations with URL mapping route different aplentmentation that is up to the setup correct configuration. So to be augmented as and when the need arises with the Cloud Hub balancer, dedicated load balancer and journal mapping so we can route the request and all through dedicated load balancer and all use via a different setup.

Now, the third guideline is to publish to any point exchange using the fully semantic version in asset version and refer to that of the APA Manager asset version. So the three guidelines are the first two are always use measure versions only in the Ramble definitions APA endpoint URL and the APA Manager APA version and anywhere URL endpoints are coming, use measure versions only in your URL versioning. Also, always use measure version only only when you publish to the any point exchange and the APA Manager asset version, make sure that you put the full semantic version. Okay? Asset versions only if you remember how you can remember or memorize.

This is APA versions wherever you see things like APA version, APA URL version and all moldy measure version. Wherever you see asset version ASCT asset version, just name it as the fully semantic version. Okay? You can use full semantic version. All right, so these are the guidelines and the ways of versioning the patterns we should follow in the PA project central versioning major minor patch and all so you know the definitions how what is the impact of major change? What is impact of minor change in patch change? When should Ape clients should be bothered or changed the code they said and when they need not okay, so hope you understood the APA in detail because this is an important concept in exam as well along with the real project scenario as well. OK, happy learning.

• Category: Uncategorized