MuleSoft from Start: A Beginner’s Guide — Session 4: Test & Publish the API Specification
In the last session, we started creating an API specification using the UI in Design Center. We designed the data types and the articles resource. Our homework was to finish the API specification for this session.
In this week’s session, we finished the design of our API specification, tested and adjusted it, to finally publish it to Exchange. After publishing to Exchange, we scaffolded the necessary flows from Anypoint Studio using the APIKit Router so we don’t have to start our Mule application from scratch.
Note: The links and some notes from the session have been added to the GitHub repository for you to follow through with what I’m doing in the video. You can find both recordings (the complete and the shorter one) at the end of the post.
Homework from the last session
After careful consideration and because I’m already experienced in RAML, I decided to move away from the GUI and design my own specification using RAML 1.0 directly (still in Design Center tho). This is the list of resources I ended up with:
/articles
/articles/{id}
/articles/{id}/comments
/articles/{id}/comments/{id}
/writers
/writers/{id}
/categories
I decided to use a query parameter on the /categories
resource to query if a specific category (string) exists or not. A similar approach would be done with the comments. If you don't want to have such a long URI like /articles/1/comments/1
, you can also decide to use query parameters instead. This is completely up to your design/preference.
Test your API Specification
Once you have a base specification, you can start testing how the experience would feel for the developers using your API. To do this, you first have to click on an HTTP method from the right (in Design Center).
Then, you can click on the Try it button.
This will let you send any Query Parameters or Headers in the request but since this is a GET method, we don’t have to send anything and we can just click on Send.
After clicking Send, we’ll receive the example we had set before.
It is important to know that this is not a working application, it is just a mock that will return the examples you set in the API specification. This is just so you can double-check all the specification details and make sure the design is correct.
Test the rest of the methods to make sure they’re working as expected or make adjustments if needed before we publish it to Exchange.
Publish to Exchange
Once you’ve made sure the specification is ready, you can click on the Publish button at the top right, leave the versions as they are (1.0.0 and v1), select the Stable state, and click on Publish to Exchange.
That’s all! We can now create our Mule project in Studio.
Anypoint Studio
You can download Studio from here and see the installation instructions here. Once it’s installed, click on Create a Mule project, add your project name, and import the published API from Exchange.
Make sure you are logged in to your Anypoint Platform account and search for the API Specification you just published to Exchange. Click on the Add > button in the middle of the window and click on Finish.
Once the scaffolding is done, you will have your Mule project with the APIKit router and the necessary flows to continue your implementation.
You can test your new Mule application by running it locally (right-click on the canvas and select Run project…).
Once you see the DEPLOYED message in the console, you can open a terminal window and send a request using curl. You can also use Postman or your browser if you don’t want to use the terminal.
curl localhost:8081/api/articles
You may not get a response back because we haven’t implemented any changes, but you can check the console for new lines being logged.
Recordings
Finally, here are the two recordings you can find about this session.
Here you can find the shorter version from YouTube:
And here you can find the complete video from Twitch:
Please let me know if you have any comments, suggestions, or just general feedback for me!