Introduction

I think it’s worth starting this article by mentioning Why am I writing it. I’ve been working with APIs for a long time. I’m talking about back when building an API was painful, and testing was close to impossible. Since working with RAML, I’ve discovered an amazingly vast amount of tools available, thanks to its community.  One tool in particular enables me to grab any existing RESTful API (built or documented/proxied with RAML), and start utilizing it without having to install any software, tools, or libraries on my machine.  More importantly, I didn’t even need research anything before using the API (I didn’t even have to read the API documentation).

What is it

Anypoint API Notebook is part of MuleSoft's Anypoint platform for APIs, and it could be considered as one of the supporting last steps in MuleSoft’s "The Agile API Build Lifecycle: Validate or not."

What can I do

Avoiding the theoretical debate of any of the steps, and instead focusing on “Validate or not”, let’s think about the possibility of having or discovering an API, and being able to immediately try it out and test it programmatically. Or even further, to write a simple script that calls different methods of this API in the middle of a particular logic. Or what about writing a full test suite that can be ran to detect if some method stopped responding as expected, or in other words, the API has changed?

In action

For this example, I will be using Jukebox, the Business Case as presented in the RAML 200 tutorial. However, the RAML file might vary a little bit, since I'm not focusing on the topics of that tutorial.

For simplicity, I will be using Anypoint Designer and API Portal for creating the API, publishing it, and most important "Mocking it". As I said before, we will be utilizing existing, live APIs to see how our API works with them as a HTTP service.

Use Case

Build a music Jukebox. While the physical device will be responsible for displaying the information and capturing the user input, it will be relying on your API to retrieve the information requested. The Jukebox needs to be able to:

• Show the full list of artists.
• Show the full list of albums.
• Show the list of artists by nationality.
• Show the list of albums by genre.
• Search for a song by title.
• Show a particular artist’s albums collection.
• Show a particular album’s songs list.
• Play a song (by specifying the song id).
• Enter new Artists, Albums and Songs (only authenticated users).

Consideration: This is a jukebox, not a command line. People in pubs might be unable to type lots of characters, so a user friendly UI (paging, image-based, etc) would be very appreciated.

Key Concepts

• AnyPoint API Notebook is an example of Literate Programming: the adopted approach is to combine code cells and text cells where to write and explain the program.
• RAML API generic client: The key factor of this tool, is the capability of exposing a specific DSL to call the API methods of each API. For example: “client.artists.get()” will retrieve a collection of artists, and the DSL was automatically generated by the tool based on the RAML definition.
• Execution responses: When running the contents of a cell code, the tool adds a response area where you can see what was the actual response for a particular call (or general execution).

Hands on

So, let's explore what's been done.

• To understand the Jukebox API used in the example, you can access its API portal.
• Check out the its API portal for visual and interactive documentation.
• Check out the its API portal itself.
• You are now ready to utilize the notebook.

The notebook, step by step

Text cells

As explained before, you can include text cells at any part of your notebook if you need to explain what your code is trying to do.

The client

Initializing the Client that will provide the DSL for calling your API methods is as simple shown in the next image

In this case, "JukeboxAPI" is the name of the variable that will contain the client instance (first parameter). The second parameter is the URL of the API RAML Definition.

Consideration: RAML defines the URL of the running API by setting the property baseUri. In this case, you will see something like this: http://mocksvc.mulesoft.com/mocks/957041d5-7af4-49f2-ae66-03da18de6983. This is basically because the running API is a mock generated with AnyPoint API Designer. If you are working with a real API, you just need to point the baseUri parameter to the URL of that API.

External libraries

You can load external modules to use these on your notebook. A great use of this capability is including an assertion framework, allowing you to write a "test suite".

Invoking methods with URI Parameters

Assuming that we have this URL resource representation "myAPI/artists/{artistId}" supporting the HTTP GET method, invoking it would be as simple as:

where "123" is the value for the "artistId" parameter. In other words, it would be doing a HTTP GET myAPI/artists/123.

Body and Query Parameters

Following the previous section approach, let's consider the URL resource representation "myAPI/artists" supporting the HTTP POST method, and expecting:

• The Artist JSON representation as a body parameter.
• An Access Token (for authorizing the operation) as a query parameter.

The first parameter of ".post" is the http body parameter. The second one, is a JSON specifying several options. For adding the Query Parameters, the "query" option is used, and the expected value is a "key:value JSON".

Assertions

Since we have included the Chai Assertion Framework, we now can use it to compare the actual responses with the expected ones:

Next Steps

With the information provided in this article, you should be able to read the entire example notebook, run it (yes, it's the main purpose of this tool), edit it, and finally, write your own.

I hope you find this to be useful. Feel free to contact us if you have questions. Cheers!