API Modeling

5. Designing and Publishing APIs

Hi. As discussed in the previous video, we will now look into how to publish API returns to any point exchange. So how is this different from the previous demonstrations, where, early on in the previous demonstrations, we had published the APIs to any point exchange already, right, from the API designer? So what is going to be different is that this one is going to be more elaborated. So here I'm trying to show you in the standard way, the actual enterprise standard way, to actually create the specification of an API in the Design Center and how we have to publish to the exchange. Okay? So before we start, all things considered, what I'm going to do for COVID is show you clearly how to use the Design Center to properly sketch the API specification, which will be RAML. And when we talk about RAML, we are not going to just create one bulky RAML for our use case, create a sales order, and publish it to any point exchange. We are going to do as we would in the real project, meaning we will divide the Ramesh into smaller fragments.

Okay? So at any point on the platform, we can actually create these small API fragments in the Design Center. So if you're not aware of what an API fragment is, just to give a quick background, So APA fragments are smaller portions or modular portions of the APA specifications. Okay? For example, let's say we take the use case of our sales order creation. So in the sales order creation, obviously we have an API that will have a version protocol description, and then we give the resource an http verb like "get post," "create," etc. And along with that, we also give what kind of body is expected in the request, which we are going to do like a data type or a schema, right? So we have to put that in; okay, this is the schema of the request to create a sales order. Similarly, we will generally create a response schema to say that, okay, this is what the response looks like, right? And that is usually enough for the creation of the large side. But in fact, we don't even need the data types to be defined in the RAML. We can just say, "This is my resource in the http verb" and publish it to any point exchange. It still works. But what we are talking about, as I mentioned a while back, is that we want to create an API standard or an industry standard API specification. If we just publish a normal one, then still the consumers do not understand or do not know what the actual format of the request is or what response they have to expect from the API.

So specifying these request and response schemas as part of this full and exhaustive RAML specification helps them actually understand that, okay, this is the request and this is the response of the schema, right? So what else? Next, we can also give examples to make it more user friendly. Right? We can say, "Okay, for this request schema, this is a sample example of how it looks for this response." This is how it looks. So we can put all this content in Rameland, exhaustively and extensively define it, and make it more heavy so that it helps the consumers to the maximum extent. Don't mistake the word I used, which is heavy. When I say "heavy" in the context of the Ramese species, don't take it in a bad way. Okay? So this is not something like a bulky or heavy code. This is a specification-wise question. So in the specification category, I feel like the word "heavy" is good because the more effort you put in during the spec phase and the more effort and hard work you put in deriving the spec, the more success your API actually has, you e spec phaBecause upfront you are telling everything about our API crystal clear to your consumers, saying, "Guys, this is my API," This is what it does. This is the version This expects only the HTTP protocol. This expects these things to be done. This offers these resources against these HTTP verbs. These are the query parameters, and these are the request formats. And this is the response you get if you still have a doubt; look at the example. So it's very clear that you can do a lot more.

I just gave a few of them. Okay? All right, so this is a high-level, detailed level of what we are going to do in this demonstration. All right, now, so again, what I want to say is that the interface detail should be exhaustively specified in the RAML, like schema examples, requests, responses, enumerations, et cetera. And all of that, even the security constraints like HTTP protocol, can be done. And we will also discuss versioning to tell whether it's a draught version or what the maturity level of the API is using the version concept in the RAML design. Okay, so one thing is, like I said, we will not just put when I said heavy, right? We will not put everything in a single RAML. We will use an industry standard method for creating the AP fragments or smaller portions. So we'll create one request schema APA fragment, one response schema APA fragment, and then examples of APA fragments, all right. Okay, so let us jump into the Design Center. So this is the landing page of my anypoint platform. We can go to Design Center either from the landing page or from the left-side navigation bar, where it is Design Center.All right, so let's enter the Design Center. Now, how can we create these APFS fragments? Actually, it's the same way we did it last time, when we created the RAML specification. All right, so we go to the "Create New" button here. It will give up with the options asking whether it's a Mule application or API specification. So here, if you notice, there is a CreateAPI specification as well as a create fragment.

So this is where you have to choose. So the AP specification is like the base one or the core one, where the root RAML resides. But first, if you want to go with the fragments of smaller pieces first and then form the Rammel letter, you can very well do that. So that is the approach I'm going to take now. So what I want to do is first create the request schema, response schema, request example, and response example. Okay, once that is done, then I would like to move on to the RAML by using those components. So what benefits do we get by fragmenting this? Why do you have to create APA fragments? How does it differ? Is it just that the RAML won't look bulky? No. Okay, yes, that is one benefit. The Rama won't look bulky, but another benefit is that these fragments can be reusable. All right? So when I say "reusable," the same request schema might be useful for a different API. That API may not be for creating sales orders, but maybe it's a different API where it has a complex structure of requests nested deep down somewhere. It needs this particular request as part of it. Or maybe it is some retrieve API wherein the response needs that structure of the request with the same fields and all. So it's just the smaller piece, right? so we can reuse it wherever it fits. Okay, it's up to the design. We have to see if you notice that. Okay, for example, it's a billing object. So a billing object is something like this: it has some attributes like account number, amount, installment schedule, et cetera, et cetera.So this is one reusable component. Similarly, another section is called "customers." It has a first name, a last name, and all that.

It's just a customer schema. So it has no context, only for order or somewhere else. It could be a true customer. It could be created anywhere. So you have to identify smaller pieces contextually and create them as schemas. If you have ever designed the canonical models, even in XML or any other formats like JSON, then you would know this, right? Let's say you take the accessories only. So we have access to both complex types, right? and simple stream types. So one complex XSD can have nested complex access. We generally import the other accessories onto a bigger access card. So smaller accessories are like Address D, which has address lines 1, 2, and 3. Another can be Contact Access D, which has a phone number and an email address, and all three could be Customer Access D, which has a first name and a last name. So you get the context of what I'm talking about, right? So those existances are like the fragments here. Okay, so let us proceed without wasting any time. So I'm going to click the create segment button so I can give it a name. So for the sake of simplicity and brevity, I'll just use the sales order request schema, okay? and it will ask us the type of fragment here. Okay? So don't get confused because the type of fragment it is asking for is The APA Exchange actually supports many types of fragments.

It's not just about the data types of schemas, okay? It can be, like I said, an example, a simple annotation, or a security scheme. Anything that is reusable can be created as a fragment. So in our case, it is the data type. So I'm going to select the datatype and I'll say "create a fragment. Okay? It will be created soon. So here it is. It has created the blank-request schema designer canvas. Okay? So now what I'm going to do is quickly fill up the request schema. Okay? So what is my request schema? which is nothing but the sales order. Create sales order details. If you remember in the video where we designed the use case for the great sales order, we said the request would come with, say, customer ID, shipping location ID, and the item numbers. Remember, that's why we have validate customer ID, validate shipment location ID, and validate item. So let us put those things in the request schema. Okay? So I have to clearly say that. Okay, properties If you see, I mentioned that the properties of my listing are: the first one is customer ID, and I would like to give the type of the type as a string, and then is it required? Yes, that's always true. Okay, and the next one is the ship location ID. Again, usually this designer helps you auto-populate and fill in the details. Okay? So if you see it, it will come here and you can choose if you are comfortable. You can straightaway type it and finish it, or I want to show you the features of the designer. So I'm waiting for it to load. Okay? And then again, you can say, "Okay, is it required?" Yes, always. I'll just say "required. True. And then we have the items. So I'm going to give it, instead of a flat array, some more details to make it more contextually fitting. So line items are off in the array, right?

So I'll have to give a type array, and then again, this is required. Yes, required. True. I'm going to type now on because I don't want to wait for the auto populate to load, and because it's an array, what are the elements inside this array structure? So usually we give that as an item. Okay? We always have to say, "Items," and "What are the properties inside the items? Items. And again, we'll answer the same way, saying okay, item ID, which is again an off type string; is it required? Yes, group, and then quantity. Okay, I'd like to add the required group, and then I would like to add the quantity because whoever is ordering should mention, "Okay, I want whatever this much quantity for this item." Right. So as in, when you type here, you can also see that your details are coming in here, right? So you can see that. Okay. It is determined by the type of customer and then shipping loan location ID. And then it is line items in an array. And if you show it, it says inside that it has an item. Items have an item ID and a quantity. It's just still loading. So that's why you should Yeah, it's item ID. Okay. All right. So now let me save this one. Yeah, it's saved. So what I'm going to do next is publish this particular fragment to the any point and then shipSo I'm just going to say "publish" to exchange. I'll just wait for this thing to go. I don't want to show it as an error while publishing it in front of you. It's a bit slower because, in the trail version, it loads from the US. Generally. So all the trailers are created in the US. AWS instance by mule. Soft. I am in Australia, so it takes time to load. Yeah. Okay, I'm going to publish now. Come on. Yes. So I'm going to give the version as one. Like I mentioned before, this is where you have control. I wanted to say this is still not very much matured.

Maybe because this is the first version, I do not want to be confident and give it a 10. So I'm going to give a zero and I'll say "publish." Okay, that doesn't take much time. Please be patient. Yeah, done. Now for the second one. Right, let's go back to the design centre again. Create one more fragment in the sales order response schema. Okay, again, it is a data type. Yes, create fragments. So we'll repeat the same exercise again. Yeah. So it's the same is the first verI'm going to give them one by one in the response. Obviously the properties—where else would they go? Obviously, the order number would go, and the order number would be of type string again. And is it required? Yes. Obviously, if the order is created successfully, it would be required at 100%. Right. So I'm going to give as required. True. All right. And then the second one is that I'd like to give, along with the order number, the line item details. Again, the reason being that the logistics company may not actually deliver whatever quantity they have ordered. Okay. So we saw that in the quantity ordered field in the request, they changed item 110 quantity to item 20 Obviously, if But they may not have ordered due to the availability of stock or something. So for that reason, we'll give the items back with one extra field called shipped quantity.

Okay. You'll see that now, right? So properties, and then we are going to say, "Okay, I give you item ID, which is of type string required crew, and then ordered quantity to specifically say how much they have ordered the customer." And then the last one is the shipper quantity. All right. I'd like to change it to an integer. My mistake. And then, yes, even this is a required group. All right. So we are done with the request and response schemas. Okay, I'm going to save this. We'll wait for this thing to go. And I want to wait for this to load because it has the red colour thing in the middle. But I think it works. Okay, I'm a bit confident. Okay, I did my homework.

I'm sure this will work. Let me publish anyway. Okay, I'm sure it will work. Okay, I'll put publish on exchange. won't take much e to changNow, examples. One for a request, one for a response. Let's go back to the design centre and create one more fragment. Sales order request example I'm going to select this as an example and say "create a fragment. All right. Okay. So I'm just going to remove this and say, "Okay, I know my field names; I remember." So I'm going to say the customer ID is SEC 1, and then the ship location ID is SHPL 1. And let's say after customer ID and shiplocation ID, or what were the other things? Yeah. Line items. Right. item ID and quantity one, and then line items. So this is an array. So I'm going to have to give like a dash for the notation, and for each dash it presents one array element. And in that, I can give, like, okay, item ID is IPM zero one, something wrong one, and then quantity. This is a number that's a ten. Okay. And then, for the second, I would like to do two array elements. Item ID. Again, ITM 2 and then quantity 15 this L 1. And lSo this is an example of a request example.I'm happy with this. I'm going to just save this ? Yeah.

LinAnd I'm going to publish this to the exchange as an example. ems. So thSo again, zero, zero, one, publish to to give like aLast one response Create a new fragment. Sales order response example I'm going to select an example again. Create fragment. Okay. So again, I think it is the order number, which I'm going to give like an ODR one, and then line items because it's an array. Like I said, I have to give a dash notation, and then I give the item ID, which is ITM triple zero one, and the ordered quantity, which is let's give it request ten, and the ship quantity, which is let's say eight. And then the second one, item ID. Item two was ordered at ay. So agaiOkay, I think that's fine. Makes sense. Okay, I'm going to save this keystroke. So let this red thing go away. Anyway, I'm going to publish, not to waste time. Okay. Zero, zero one, publish to exchange. won't take much time now. Actually, we finished both the request schema and response schema, as well as the request example and response example. However, on the fly, ad hoc, I thought of one more fragment that we can use in the example so that you can also know how to do it in real life, right? So that is trite. You must have seen that in the dropdown when actually creating the fragment, or something called trite. So what are trites? If you already know that is good, but if you never heard of it or never came across it, then trites in the Ramel specification world are a piece of snow. You put it the same way as the other request-response schemas to specifically tell that what is mandated by the API to enforce the clients to meet that particular requirement can be represented as tuples.

Okay, so what are going to be trites in our case? What am I going to create? So what I am going to create is, because I wanted this to be close to the real life example, I wanted to enforce on my API that the clients must pass the client credentials in the API they are going to hit in the HTTP headers. Okay? So for the API, whenever every client hits the API, I want the client ID and client secret, which are called client credentials, to be passed in the HTTP headers, okay? So in the same way, I want one more field to be passed in the header, which is the transaction ID. Okay? There is no specific reason. The main reason is because I want to track every API. Maybe I have a logging framework or even some analytics solution where I want to put a transaction ID and track the whole transaction. So if I enforce my clients to pass transaction ID tomorrow, I can uniquely identify every request and response that is coming for the transaction. Okay? So I'm going to create that particular track. So I'm going to create it as a fragment again, and I'll say "custom header no." Let's say organisation the same wAlthough it is trite, I am going to choose the library here, okay? I'll explain the difference; don't worry. You might think this guy just said he was going to create and write, and now he's going to create a library, okay?

So I can go with right as well. But let me explain a different difference. Being a library is a collection of multiple books, okay? Not just right, but a collection of multiple things. So I have three mandates, like I told you, right? I want client ID, client secret, and transaction ID all. So if I have to use all three, I have to either create three types or two types of combinations and then use that in my ramen, or I can create all of them as a library and use a single one. Okay? Why I prefer libraries is because I'm sure for all my APS I want all three of them. So I don't want to create three separate types and all. So I'm going with library, can go witSo I'm going to get this fragment, so I'll first give the like version, which is I want to give us version zero because it's still not that mature and users are trites. This library resists, and I'll try to jump into the trite section. So I'll say trite, and what are my trites? The first one is the common header stride, which is now. My common header for all IPCC is the transaction ID, which means HTTP headers, and what is the header name, which is transaction ID? Okay, transaction ID and the same way we give it in the data schema will give it the same type: string. Is it mandatory in the trade or is it optional in this trade? So I give "required" as true, and yeah, that should, and the second right, which is again, which again forms a combination, are the client ant to give us verSo I'll give client credentials as another trite thing, which is also headers. So what header is client ID, which is again of type "string," and is it required? Yes, compulsory. And then the second right is client secret. Same thing, type string and required. Okay, so this finishes my right. Okay, okay, I'm going to publish it now. Alright, again, zero, zero, one publish to exchange. won't take much d the sameAll right, so now I have all my fragments ready, right? Request response schemas and request response e or is it optOkay, so now what I'm going to do is just quickly show you how they will appear in the ght, which is So if you see under all with me, you obviously see the admin math APIs, which are older ones. And if you see APA-specific fragments here,

okay, I have five of them. One is the trite example; we just created the response example, the request example, and the request and response cameras. So we have this. So anyone who wants to reuse these fragments can go ahead and reuse them in future APIs. Future Ramble. Specs. Okay, now let's fill this last piece, which is our actual RAML specification. Okay, so let's see how easy it becomes now. All right, so let's go now and create the actual API specification. I'm going to name it "Sales Order Expi. Okay. because it's an experience. API. All right, I wanted this to be an experience API. Sales order DXP API Yeah. So now let's start. So what are the important things here? Number one, you have to give a title, which is already there. Good. Number two, we should revise the Ramel. So let us give the version as v 0, like we discussed in the previous video, right? This is not a mature specification yet. Importantly, there has been no implementation yet. So you want to convey that this is just a draught version, right? So let's put V zero, and then what else? The next thing is that I wanted to clearly state the protocols. Okay. So yeah, see if it's already there; I wanted to put the protocols as https only. All right, I do not want anything else. Good. Now what next? So one more thing we can specify is our price, right? We want to enforce this API's particular HTTP headers because So for that, we already have a reusable API fragment. So how do you import them to this particular specification? So what we do is, if you see generally I don't want to show this, but I'm just showing for sake of lending. Generally, if you don't want to use the reusable ones, create them there, and then you can very well go and click on this plus icon, say "new file," and create each file as an individual fragment and use them within ero, and thBut they will be limited to this particular specification only. Okay. They are within the scope of this.

They are not visible to other specs. But if you have a usable one in the point exchange like you saw a while back, which we created and published, we can go to the exchange dependencies, click on the plus icon here, and it will load you all the usable components. Okay. So instead of saying "all," list the entire new software repository fragments instead and let's go to your organisation or a particular business just showinLet's say organisation would be now you will see clearly all of them here because we are going to use all of them anyway. Not only is that just right, but I'm going to select all of ile," and And I'm going to say, "Add all these five dependencies to my specification project." It won't take much d to this They are now loaded. So now what I'm going to do is, in order to use the trade, I will say uses okay. I think this is the format. Extremely sorry. Yeah. I think now it should be validated and made successful. So now that we have the tool to tell which trip is next, we can go ahead and create our it will load ySo what is my resource? My resource, which I would like to name Create, And once I say "create," I have to obviously mention what type of method it is. It is a post one, and once it is a post one, I'd like to also give a description of my particular API. So I'll say okay, the description of the API is to create sales and orders in the ERP simple description. Now, the next thing is that I want to somehow okay order in the ERP keyboard issue check back. Okay. Yeah. Now next thing is I also mentioned that I want to enforce this headeron this particular resource, the tries one. So we have to use the easy one. If you see its types and rates, we have to say "ease," and then we can say that the test was okay. should be And then one more thing: the client credentials. So I'm going to mention this, and I want to have my client credentials. It's auto-selecting anyway. Yeah. So I mentioned And then first the price on this particular resource.

The next thing is obviously the body. So it's an application of the JSON type. So I'm going to select that, and once I select that, I have to select the type. Now, okay, so I said type, and what I want to see is that I don't want to use any of this type. I'll say I want to include the one I created, right? So once I include it, it starts suggesting that I exchange modules. And then I want to use my schema, which is Request Schema. Okay? Now, once that is done, the next part is the response part, right? So I'll go back and say responses, and in the responses, I want to just concentrate on the 200. OK? Now, when I say "200," obviously there is a body. And what type is it? Again. It's application. JSON, and again, that application's JSON structure. I can select the type. And I would like to go with my include again for exchanging modules, sales orders, and response articular resOkay, something is wrong. Okay, I'm sorry. I have to select the version and then the RAML, right? Yeah, the same way we select the types. Even here, I have to select the version and then the RAML. Okay, so now I have included both types. So if you closely notice as we fill in here, you are seeing the API summary details on the right side. See my API title version, the supported protocols, and then the Methods Resource Center method. So if we click on this post, right, it will already start giving you the suggestions that consumers will already know. Okay, there are no code examples as of now, but if you see it, in the headers, transaction ID is required, client ID is required, and client secret is required. And it automatically generated a sample request example for me based on the schema.

Okay, if you notice, I have not even mentioned my actual example. Remember where we gave quantity as ten item ideas? ITM (triple zero one). Still, this is implicit enough to create an example from the schema itself because it contains the structure, the data type, and all. It is showing me how it looks and all. But let us go ahead and give our examples as well. So I'm going to select an example, and I'll again try to include the one fragment that I have created. So I select Include and then Exchange Modules, my Sales Order Request example, this one version, and then the final piece, which is the diameter. Similarly, I don't want to waste much time. I'll just copy paste this and continue from the piece here. So, yeah, the Sales Order response example version is triple zero one, obviously, and then the Ramel. Yeah. So now this is full, right? So if you see now if I revisit this again, as you see in front of you, this change is to the proper example. C one SPhP shipping location, item, and quantity This is the request, and the response is this shorter shipping condition and the order licit enough So beautiful, isn't it? So now one last thing I want to show This is not just a feature of any point exchange. There is more you may have already learned for you. If you already know this, then you may think it's not a great thing or a great deal, but for someone who has not tried it before after this exchange or API gateway tool, then it's an interesting thing. See how consumers can now even interact more. This is actually enough for the consumers to start their work, right? They know everything about what to do or how to call the AP. But still, if they want to try it out, there is an interesting feature called "Try It." So if they click on it, they can very well go here. It gives them a real console where they can try. It's called the API console.

Okay? So I'll put my transaction ID as txnido one, and then I'll say client ID as CID and client secret as C secret. For example, this should be the kind of currency that we usually acquire from the endpoint exchange by requesting access. But I just put some dummy values now in this application's content JSON; I already have my sample request, which is the example I have given. I'm just going to send it and see what happens. Now I'd get the response back. Oops, it's saying "400 bad requests." I must have done something wrong. What did I do wrong? Let's see the details. It says the 400 Bad Request Protocol is not allowed, okay? Because I said only HTTPs are allowed and my protocol is not allowed because it is HTTP or a dummy HTTP. So what I will do is first enable the mocking service. All right? Let me enable the mocking service so that NewSource will generate one mocking URL for me. See if you see it. Create a base URL with https. Now let me try the same thing again. Txton ID Two tests, two CIDs, two C secrets—same thing. I'm gonna hit it again. So this time it's 200, okay? And I got my response back, which is this. If you see this, this is my response. Don't worry. Why does it look like this? It's just a table format. But if you see the source view or something, this is the actual JSON format. I got my response back. All right? So beautiful, isn't it? So the consumers can right away know what it is. But you may think, "How can consumers come here and test this?" Because this is design. This is only something that developers and designers will have access to this. What is this guy talking about? How can they come here and access this epic console here? No, there is a single console as well as a place for exchange, which I'm going to show in a minute. But even while the designer is designing, this designer can log in to the Epic console here. So it is all good to me now. So what I'm going to do is publish this to the exchange because I'm happy with it.

So let's go and click on "Publish to Exchange." I'm going to put it at 0.0.1, and the AP version is nd I gotSo using this versioning now, if you establish the standard in your organization, everyone will know that, okay, this is still not a mature level one or that the AP implementation is still pending. Okay, so how it helps them is that this specification acts as a stub until the API is fully ready. Okay, why stub? Because it still works with a request and response structure, all as per the examples and schemas and everybody knows how to use it. So they can still start client-side development using the system. So when a system is used, there is an interactive way as well, right? So using this mocking feature you saw, right top, right. They can actually go, and API clients can interact with the API. So how the actual clients will do, I'm going to show now, because this designer piece is here, which is fine. So how can the APA clients respond if I publish this now? Let us go to the exchange. Okay, so along with our existing fragments, you will now see this particular fresh API as well. All right? So if you click now, Exchange is somewhere anyone in your organization or any consumer can visit, right? So they may not know what is in the center, but when they come and search for the assets, they see this. So when they see this, they know, "Okay, there is a sales order experience API." So they can click it here and see, okay, what operations are there. So when you publish for the first time, you can actually add the proper descriptions. And also, remember in the previous video that whenever they search with the keywords, it actually searches the title, such as the description, and all other content on your page. So I'll say, "Create a sales order API for ERP." Okay. And I say here, I'm going to say, like, supports, create, retrieve, update, delete sales, order, save as draft. just some names. I just want to give some names. Okay. and exit draft. I'm going to say "publish."

Okay, so now I have some descriptions. So when I search for any of these details, it will end up here. So the consumers will see this. They know what operations they have. And if they say okay, what are the details of this particular resource? They can click on the post. And the moment they click on post, the moment they click on post, they see the same API console. Even here, they see the details of the base Uri. They see the coding examples. Like, if they want to hit from curl, they want it from http JavaScript code or Python code. It gives all the ways you can hit the particular rest API. Okay, all the popular ways. See, you can just copy and paste this. The clients can copy and paste this and reuse it with slight modifications like handling, et cetera. So whatever you saw there, it gives here in the Ape console, in the designer, as you see in the exchange. So consumers can see here that they get all the details: the request came, the response scheme of what format was used, et cetera. And if they want to try it out the same way the designers can, the consumers can also try it. If you see, I'll fill in the TXNID with three consumer IDs and a consumer secret. And then I'm going to say send, right? You just send it the same way you send it to the API designer, how it works, and how it works from the consumer's perspective as well. Okay? All right, so I hope you learned a lot from this particular demonstration. You now know the right way to create a specification with fragments and will try to implement it in your projects. If you are already in the subproject, or I hope it will come in handy for you in the upcoming project, if you are going to work, Okay, thank you. Happy learning.

6. API Documentation

Hi. In this lecture, we will look at how to create proper documentation for the APIs. Any Point Platform actually provides two main features for making the perfect documentation of an API. The first one is using API notebooks, and the second one is using API consoles. So again, Any Point Studio and AnyPoint Exchange are the very entrypoints for an API, according to the documentation. So, what did we do as soon as our first API draught of the Ramble definition, say, for our CreateSales Order, had been created in the Any Point DesignCenter?

We published it to Any Point Exchange to inform everyone about its addition to the application the applicati And what we also did was use the versioning to reflect the maturity of the API or the Ramble definition. Like we used V 0 for the RAML specification to indicate that this Ramble is still like a draught version, And also, we used zero zero one for the API in the Exchange asset to tell again the maturity level of the API, which is a new API that has not been implemented that has nSo after publishing our API to the Exchange, we need to manually add the content to the API with that particular Exchange set. Okay? When I say "content," I mean the descriptions and all other kinds of documentation. So what kind of content or documentation should be added? So that content should be some things that cannot be expressed in the Ramble definition because, remember, we already tried our best and exhaustively developed the Rama specification. We tried to include as much as possible in the Ramadan specification itself, including the title version, the protocols supported, the headers that are mandated, the resources, descriptions, example schemas, everything. So if still there are some things that are descriptive in nature and which need to be known by APA consumers and all, then that kind of content can be added to the Exchange description. Okay? So if you remember from our previous demonstration, just for example, I have added a small description after publishing to the Exchange saying, "Okay, this API is to create orders in ERP."

And I said it supports—create, update, delete, and retrieve—something like that, remember? So just for example's sake, there could be many other things you wanted to add there to explain your repayment policy to consumers. That all can be added there. Okay? Also remember one thing: every change to the content of the RAML definition actually triggers an asset version increase, incrementing a particular asset version in the corresponding Any Point Exchange entry. Meaning, let's say now, on top of our asset-test example, the Ramble of Great Sales Order, we have gone there and made a minor change. Like, we either updated our example or we have added one more resource. If you remember, we only added "create resource" with the post, right? Let's say I added a retrieve resource called Gettype get" and I just saved that and tried to publish it. The moment I tried to publish it to the Exchange, my previous zero became 0020kay. So it will automatically increment. Even if you manually change it back to one and try to publish, it will complain, saying a version already exists. So you have to compensate and make the adjustment. Okay? So this is a mandate. This is to maintain pure versioning of your changes on the Ramble and the Assets. All right, now let us discuss our documentation methodologies that the Anypoint Platform supports. Let's take the first one, which is the API Console. Okay. API platform automatically creates a Web UI to browse and trigger the API invocations of a particular API with the APA specification, meaning having the drama and all. So this particular feature is available in three places.

One is when designing an API in the API Design Center, like we did in the previous demonstration and in the previous lectures, in the Design Center itself, as we design and document our RAML on the right side, you will see the auto populated radio version, like the API Summary. And even you can try it out by playing a sample message by filling it in using a mocking like the API So that right side panel is nothing but the API Console. Okay? So it is provisioned in the APA Design Center. And in the second place, I think you already know the answer because you have seen the previous demonstration: the Any Point Exchange Entry. So as part of an API, is any point exchange entry, as well as what you have seen in the previous demonstration, possible? We can click on a particular resource and go to its method. And once we do that on the right side, again, the same API console appears where API consumers can go and try out their APIs. And the third one, which you have not seen yet, is in the Anypoint Studio. All right, so I'll try to code that. In the next demo, There's a short demonstration to quickly show you how it looks in the Any Point Studio. But even in Any Point Studio, when you implement an API, and when you run that API for the first time—or not the first time—anytime you run that API, then in the studio also, that particular API console gets generated and launched, just like a web UI.

So you can even try out your stuff there as well. Okay, so this is about the API console, with which you must be familiar already, because you have seen it and we covered it as part of the previous demonstration and the lecture. But now the second one, which is a new one, is the API notebook. The API notebook for an API makes use of the RAML definition for that API and provides an interactive JavaScript based coding environment that can be used to document interactions with the particular API from the point of view of an API client. If you are an API client and a consumer, you want to use an API. The API notebooks come in handy by giving a JavaScript-based coding environment where you can write code and they can play with that snippet of code Snippets by clicking on them, saying, "Okay, how would this execute?" and all, and seeing how the responses would come. They can be interactive. Even the API console is interactive, but they just play the message and give us the response. But if they want to see a kind of coding way how it will execute, that would also come in handy in an IP notebook. Okay? Now we will see a short demonstration for this as well as after this lecture on creating a simpleAPI notebook for our sales order API. Okay?

And lastly, as part of this documentation thing and Any Point Exchange, I would like to say that after publishing to Any Point Exchange like we did for our sales order API, we can also publish those APIs on Exchange further to the public portal or developer like to say This is something you have not seen in our previous lectures for the demonstration videos. I will try to COVID this as well in the next demonstration. So the public or developer portal is a portal for an organisation where they can host some of the APIs publicly. Okay? So what is the difference? Exchange endpoint Exchange can help users who are authenticated to the Nippon Platform, right? Because unless you log in to the platform, you want to access the endpoint exchange. And if you can't access the exchange, you can't see the APIs, right? But that is secure as well. If you want your apps to be internal to your organisation and secure them, that is fine. All right? There is no purpose for the public portal there. But if your organisation wants your APIs discoverable on the public internet or just some of them, not all of them, then the public portal or developer portal is the place where such APIs are to be published. You will see that in the demo and even platform, and MuleSoft allows you or your organisation to customise the portal by default. The native loop is a little bit like the Amule soft theme, but it also allows you to customize, say, the logo or banner and some of the skin elements of the public portal. And then what you can do is cherry-pick some of the APIs on the Exchange and publish them to the public portal.

So the general thumb rule here is that this is an important thing. Remember this general rule here that you need to follow when following these three layered architectures (APL). Connectivity based APS means that you never ever publish your PRC, which means process APS or the system APS, to this public portal. I will not particularly explain. I guess, you know, someone must know the reason. But I'm just telling because, as we discussed in many lectures before, Process Layer and System Layer APIs are the Orchestration Layer and the Backend Layer APIs, right? So there is no reason why you have to publish it to the public portal because the Experience Layer is the one where the APIs are built for the purpose of consumers. So if you ever have to publish any of the APIs to a public portal or the public internet, then obviously they have to be EXP Layer, which is Experience Layer. It cannot be a PRC process layer or a system layer. Right? So please remember that. So only the cherry picked APIs that are experienced APIs can be published to the public portal. Alright? So without wasting any time, let's jump right into the demonstration in the next video. Happy learning.

7. Demo - API Documentation

Hi. Let us jump into the demonstration. The first thing I would like to do is show you the API console in Anypoint Studio. Because, like I told you in the previous demonstration, you have seen the API console in the Design Center as well as the API Any Point Exchange. But you have not seen it in any point studio. Right? So I'm going to show you quickly that one. It won't take much time. Okay, so what you're seeing in front of you is a sample project that I have in Any point Studio. So it is nothing. But remember the Math API that we have used in the Anypoint Designer for the early lectures and demonstrations where it adds to numbers, right? So it's the same one. I have imported this math API and created a small application that does nothing but add the numbers. It's a small data view that I have, which just adds the two numbers and all. Okay? But anyway, we are not going to execute or do anything because we want to only concentrate on the Any Point APA Console, right? So I am going to just run this particular application, and we will just see the application run. And yeah, it's running in the console logs. So once it runs and is successfully deployed in your local environment, you will actually see a new tab coming out that says something like "APA Console.

Okay? So, yeah, just like you are seeing in front of you now, you will see something called APA Console. It's again web-based. So, because as of now, my Ramel or API has only one resource, we are seeing only add ins. So just like how we click in the AnyPoint Exchange, you can click on this method, and it will bring up the same kind of documentation here. Because in this one, this particular RAMWELL is not as exhaustively or extensively built as our sales order example. You are not seeing any descriptions or security schemes. Otherwise, you would see https, the description of the API, and all the schema, which is all you would have seen. But in this case, you're not seeing because I only give you examples. Again, in the same way you can see here, we can actually try out the IPA. Say I have an example where number one is one and number two is two. I'm going to click post and just run it like a simulation behavior. And if you see, I got the response 200 back and also the body result, which is result 4. The sum of one and three is four. Right? So this is how the API console appears in Any Point Studio. Okay? Now let's move on to the next parts. The next part is that I would like to show you about versioning. Right? Remember, one particular portion of what I mentioned is that any small change in the major asset would actually force you to publish as a new exchange. Asset, right? So I would like to quickly show you the sensitivity of that particular thing. So I'm navigating to the any point exchange, and I'll try to pick up the same asset that we published yesterday. So if we see, we have only one version now, zero one. And you know what the content of Ramble is anyway; we are going to the Design Center now. So, as you can see, as of now, we only have one version, which is our very first draught version. So let's go to the Design Center now, quickly.

Here we are. And let us open the sales order envelope. Yeah. So what you see in front of you is the first version that we have published, right? So now what I'm going to quickly do is alter this or make a small amendment, okay? So what I'm going to do is just add one more resource called Retrieve. Okay. Let us say this is for retrieving a particular order, okay? And I would like to have it as a gift, okay? And I'll just put the description retrieves sales order," all right? And I will just put body and application. Jason I'm not going to apply any types or anything for now to make it simple, okay? Body and it's of type application JSON. Similarly, we can also say quickly that the responses are like 200 and the bodies again of the type JSON. Okay? Done. Right. So I'm going to keep it just like that, okay? I'm sure this is also allowed in the world of the Ramel because it is not necessary that I have to give my type and example in order to publish it, as you can see. Still, it renders the operation all but impossible. The only difference would be that when I click on this, it cannot show me a sample request or response, e would be thaSo now what I'm going to do is just publish this particular asset, and if I try to do that, you can see that it will actually increase the version. If you see it is now forcing me to put it, as in, I forcibly make it one," is that okay? I don't want to change it to two, so I'll just go ahead and change it to one. So if I try to publish, it is complaining that publishing to exchange the asset cannot be created because it already exists with the asset ID.

So what is the asset ID? Asset is nothing but the version combined with some of the name, all right, so let us respect its previous decision and change it to two, okay? Now it has been successfully published on the exchange. So let us go to the exchange now and let us open our API. And if you see, we have a second version, which is two, okay? Now, you may think, "Okay, what if I delete the version and try to give it another while publishing the Ravel from the Design Center?" But you know, it is smart. It still doesn't allow you, no matter if you delete the version, for example, not one. But if I say go and delete the two versions now to keep the one back, yes, it goes back to one by default the moment we delete zero zero two. But now I go to Ramel in the design centre and again try to publish with some more changes. And because this time there are no two, you may think that I can again give you a fresh version of two because you made sure that you deleted this. But no, still, it maintains the complete history, and it will only allow you to start from three. Okay? There are very straight versioning rules in the platform as well as in Any Point Exchange. All right, so this is how sensitive the versioning is. Okay. Now, because we are on the Any Point Exchange already, let us discuss the next part of the demonstration, which is our APA notebooks. Okay? This is also something you have not seen in the previous demonstration because you have seen AP consoles but not the APN notebook. So like we explained in the previous lecture, the APN notebook, like I said, is like a kind of code that is in a JavaScript based environment to just make it interactive so that the consumers can just play the snippets and see how their responses would look at different stages. Okay, I'm not going to write an extensive APay notebook, but I can just write a couple of steps to show you how it would look. Okay, so let's say this is the Any Point Exchange page.

So once you first publish, usually this place will be empty. You have to come and fill in the descriptions. So, like I explained in the previous lecture, you have to come and edit the Exchange asset and fill in the details, like the title or description of the asset, and then some of the descriptions that are not or cannot be expressed in the Ramel in this particular area. So if there are any more descriptive things that don't fit the Ramel specification, you can actually come and fill in the details in the description area here. Okay, same way. How are you doing this? Actually, you can add the APN notebooks to the same Exchange asset. Okay, so let's go and edit the asset. Once we edit, you can add the APN notebooks is? Actually, You can go straight into the actual description on the landing page, which is the home page of the Exchange site. And if you look here, it looks like we have many other editable options. In the last, you see something called a paybook. Okay? So when you click, it will give you the markup here. Or you can actually go to the visual mode and work there. But what I would recommend again, just to be like an industry standard or a best practise kind of thing, is that please do not use the API asset in the direct description homepage. Okay? See, there is no hard rule. You can do it.

There is no stopping or doing the wrong thing. But is the better way, like everything has a practice, that better? Create a new page dedicated to the API notebook. Okay? So it won't make the home or landing page messy. It will have a proper English readable description. And someone who wants to dive into the notebook can actually go to that page. So let us give API Notebook as a specific page. have a prSo once I enter the API notebook now, you can start giving your API notebooks here. You need not worry about the very detailed description. You can just concentrate on the notebooks themselves. because this page is dedicated to this. So I'm going to say how to actually make a call to this particular sales order API. So before doing this notebook, So because this is a JavaScript-based recording environment, it expects us to first create an APA client, okay? Just like in reality, an APA client has to take the credentials, establish himself as an entity, and then call the API. Same way here, we have to programmatically create an API client. So if you click by default, the API notebook on the platform already knows that a client has to be created because this is the very first APN notebook. Because without creating a client, you can't start any other notebooks, right? So, being intelligent enough, it actually populates the code for you once we have the client. Now we can actually add one more notebook and start writing the interactive code, which is like saying we can say "client." We know the method right inside the client, which is to create one of the resources. Correct. We can retrieve and create.

So I'm going to say "create." It is a method post. So I'm going to say "post." And I'm going to just leave it null, for example. Let's see what happens. I want to show you what happens now. So I'm going to post call the resource with a null say "post. Now I'm not passing anything. Now if I play the notebook, it will execute this sequence of notebooks, and as you can see, it is now throwing an error that the schema of the content type application JSON is invalid. Because my content type is application JSON and I'm passing null, it has failed my particular call. Okay? So now that means I have to pass a proper structure. So how can I do that? So what I'm going to do now is go back, remove the null, and put in a proper has failed mSo I already have the request from our example saved. So I'll just use that one. So I'm going to now edit this book again and remove this null and put in a proper JSON. Okay? Now I'm going to play it a second time, so if you see this time that is different, it is not saying that the body is null; now it is complaining about the headers because remember, we have types of transaction ID, client ID, and client secret, so how do we pass address? Simple Let's go to the continuation to the body. Along with the body in the post, I can give options that can be addressed as well. Okay, so I'm going to just give headers and I'll say what headers I want to give. The first one is obviously the transaction ID, and I'll just give an example for now where it simply says TXand hyphen ID. Okay, and then the second thing is my client ID, and again, I'll give CID, and the third one is my client secret.

These are the three rights we have given yesterday in C secret okay, now let us try one last time Let's play the notebook now. If you see it's executing okay, it's a spelling mistake, so let me play again Allah so now if you see it's giving status 200, all the HTTP address along with my response body, which is our order number, The item number shipped to content is all right, so see how interactive it is now. I can say save it as a draft. It's the same my notebook, so it is there, and I can anytime play my notebook again, so it is going to return the responses the client has created and the board has created, so now I can say instead of exhibiting the draft, publish my details to the exchange permanently, so once I publish now one, it is permanently here, so if I again go back and reenter into the exchange asset of my sales order, the landing page and home page will have normal descriptions and details, all the resources, and everything, and if I go to specifically APA notebook, I'll have this, and I can play my notebook to see how the behaviour will be all right This is more elaborate than the APA console right now It's not just about these two notebooks; you can add more extensively; you can link to three resources here and see how collaboratively they'll work; and all in all, you can actually make a very good IPA notebook, which can be powerful and make your API successful now The last piece of this, like in our discussion in our previous lecture, is publishing some of the apps to your public portal.

Okay, so what is the public portal? I would like to first show that quickly to you. If you see on the left side of your Exchange, there is something called a "public portal." If you click on that, it will bring you to your organization's public portal. So how do you know it is your organization? If you see this URL is dedicated to your organization, it is a generic URL exchange portal, and it will have your organisation name, and organisation names are always unique. Okay? So this is your organization's public portal. So this actually works on the internet as well. I'll quickly show that also once we publish some AB. Okay, so as of now, we do not have any of the APS published to your developer portal, right? the public one. That is why you're not seeing anything. Let's say now that we go to the same sales order API and decide that you want to expose this over the public internet to the developers or your public portal. So how you can do that is you can come to the share and there are two options. You can share with your internal organization's users, generally using the roles and the users, right?

Within the exchange, whoever has access to a platform with the proper role, or you can publish it" or "publish it to the public portal," you can choose the version and say "save. Okay? Once you've done that, go back to your public portal, and let's try to refresh once. So, as you can see, you will start seeing the asset in the public portal. Now, just to give you confidence that this works on the internet, what I will do is close this; okay, let me do one thing: let me save the URL, copy the URL first. It would be difficult for me; I will copy the URL, and I will log out from my anypoint platform, on which I am currently having a session, right? I'll log out in front of you and see that I logged out. I'll refresh the page just for your confidence, just to let us know it's still there. So now I will just try to enter that public portal URL, okay? Https yeah, so if you see it's out of the session and still you see this on your API, and if you open it exactly, this looks like how it was looking in your Any Point exchange, okay? You will still see your resources. When you click on it, you will see the API console on the right side. The consumers can try out your API just like you can in your Any Point platform. You can go to your notebook and actually play it, and all the stuff will come back with the results back. So this is exactly the same. So all the hard work you did in the Any Point Exchange for creating the asset is a one time thing, and when you publish it to the public portal as well, it will come. And I also mentioned customising this, so even that is possible, but of course public users cannot customise it, right? It's an organisation thing. So you have to log into the platform to customise your public portal.

Okay? So once you log in, you will see an option called "customize." So once you click "customize," it will allow you to choose your logo, your company logo, and your favicon, like a mule. Instead of Mueller, it will give something else. Say, instead of a blue background, I will select some green, just so the colour of the text is red. Okay. I don't know. I'm just selecting some random things, and yeah, I'll just say, "Done editing, publish." So the moment I do that, it will try to change. See the color, send all to red color, and all right, so these kinds of things, if I had selected the logo, banner, and all, it would also change these things. Okay, so this is the demonstration about the missing pieces. The Ramble versioning and then the API console, pay notebooks, and the public portal Okay, so I hope you learned a lot of things. If you're not familiar with this, thank you for following the demonstration. Happy learning.

Prepared by Top Experts, the top IT Trainers ensure that when it comes to your IT exam prep and you can count on ExamSnap MuleSoft Certified Platform Architect - Level 1 certification video training course that goes in line with the corresponding Mulesoft MCPA - Level 1 exam dumps, study guide, and practice test questions & answers.