It has been a year since we kicked off Training Talks, a blog series that focuses on insightful, how-to videos that address common MuleSoft use cases and FAQs received on the forum. We started out with a simple camera in one of our meeting rooms, with the goal to help developers get quick and simple answers to their questions.
These Training Talks would not have been possible without the dedication and help of our amazing courseware developers and instructors, including Poornima, Ethan, and Mark. So this year, we’re very excited to continue this project, and bring more learning opportunities to the community.
To kickoff 2018, let’s start with a new blog post in the Training Talks series! In this post, Poornima will show us how an API fragment fits into a RAML API specification.
Let’s go into Anypoint Platform and open up Anypoint Design Center. Anypoint Design Center is used to build, test, and create Mule applications and APIs. In Anypoint Design Center, we already have an API specification created that we’re going to view. This API specification contains data types, traits, and also resource methods that are going to be used for your API.
If we scroll up to the data types, these can actually be consumed by several APIs in your organization. Right now, there’s very limited opportunity for reuse because it’s inside one API specification that you have created.
So, what if we want to reuse all of these data types in multiple API specifications in the future? What we’ll do is create an independent project that will contain these data type fragments, and we will publish the project to Anypoint Exchange to be reused in multiple API specifications.
Let’s go back and create a new project. First, create a new API fragment, and name it “retail data types.” This data type fragment is going to be consumed by multiple API specifications that are used for the retail organization that we’ve created it. Choose the fragment type as “data type,” now click “create.”
Once we’re in the “retail data type” API fragment project, what we’ll do is create individual fragment files for our customer and order data types. Create a new folder and add the name as “data types,” and then create new files inside that folder for the customer and order fragment. Our type is going to be “data type,” and this will be our customer data type fragment. Let’s add the details inside the customer fragment.
We’ll proceed to create a new file for the order data type and create the order fragment as well. We have the customer and the order type ready. Now what we can do is we’ll publish this fragment for consumption in all our API specifications that we create for the retail organization. Let’s actually go ahead and publish this API fragment in a place where it’s discoverable and can be self-served by different parts of the organization.
I’m going to delete the “retaildatatypes.raml” file that was auto-generated, and publish this API fragment into Anypoint Exchange. We can just click on this “publish to Exchange” on the top right corner, and click publish. Once we have the API fragment in Anypoint Exchange, let’s go ahead and refactor our system API, retail system API, in order to use this fragment.
Now, I’m going to go back to Anypoint Design Center, and open up the retail system API once again. And then click this Exchange dependencies icon on the left panel. Next, we click on the plus button to consume an API fragment. You can see that the retail data types fragment has been published to the retail org and can be added in as a dependency to our system API specification. So let’s add one dependency, and we’re going to go back to our file browser and what we’ll do is we’ll refactor our RAML 1.0 code to use these fragment files.
Let’s delete the details of each of these data types––the customer and order. And now open up the Exchange modules folder in the file browser section and copy the path for the file customer.raml. Add this path inside our customer variable under the types. This is going to link our API fragments into the main RAML specification. So I’m going to do the same for the order data type. Now that we have these data types, we can verify them by going into the API console and checking if these data types show up.
To quickly summarize, API fragments are reusable components that you can create and publish in order to be consumed across different APIs in your business organization. You could also have fragments within your API specification to improve modularity of your API specification. Fragments can be data types, traits, security schemes, resource types, and more as well.
Learn more about RAML 1.0 features by taking the Anypoint Platform: API Design course, and use the forum if you have any questions.
