Design an API Specification Using MuleSoft’s Visual API Designer

The first step toward creating an API is to design your API specification. The API specification helps you visualize how your API will work once it’s developed, without actually developing it. You can test your API design using MuleSoft’s mocking service in API Designer, which gives you a better feeling of what this API will look like once it’s finished. After you finish the API specification, you can later use it to automatically generate the initial base code using MuleSoft.

For this blog post, we’ll focus on walking through the visual API Designer tool and create an API specification for an example To-Do application. The beauty of this tool is that you don’t need to be familiar with RAML (RESTful API Modeling Language) or OAS (OpenAPI Specification) to create a new specification. You can use clicks instead of code.

Prerequisites

You will need to create a free trial account on the Anypoint Platform before starting. Anypoint Platform is where you can find most of MuleSoft’s product suite. In this case, we will be using Anypoint Design Center to find the visual API Designer tool.

Create an API specification

Once you sign into your Anypoint Platform account, navigate to Design Center using the menu on the left. You can open this menu by clicking on the 3-lines button at the top left corner of the screen.

Screenshot of the left-hand menu open in Anypoint Platform's welcome page

Inside Design Center, you can create your API specification. Just make sure you select the “Guide me through it” option to use the visual API Designer.

Screenshot of the new API specification page showing the relevant options

This will open the user interface, where you’ll be able to configure what you need to start creating an API specification without using any code. As you can see from the screenshot below, you can switch between RAML and OAS in the bottom right-hand section to see the code that is being generated based on the configurations from the visual designer tool.

Screenshot of Design Center's API Summary page for the To-Do API specification

Notice that there are also two gray buttons that say Edit RAML and Download. If you are happy with the initial base of the RAML/OAS code you generated with API Designer, you can click on the Edit button to get rid of the GUI and modify your code directly. Note that this option won’t let you get back to the visual designer. If you don’t want to lose the visual designer, you can download the code and open it in a different window using the code editor from Design Center. This way you’ll be able to switch back and forth between the visual and the code designer.

Let’s see what else we can do in API Designer.

Create data types

This API will be used to manage the data in our example “To-Do” application. You will need to design what each To-Do will look like, and which properties it will have. To start creating a data type, you can click on the + button next to the DATA TYPES section on the left of the screen. You can add some fields to your new data type just by clicking the Add Property button.

Screenshot of a To-Do data type showing the three new properties: id, title, and checked

And just like that you can have a basic structure for a new data type that can be reused in the rest of the specification.

Create resources

When designing an API, you want to make sure that you can provide a way for the user to perform any of the CRUD (create, read, update, delete) operations upon a resource or an object. In this case, you want the user to be able to:

Create a new To-Do
Read all the existing To-Dos
Update an existing To-Do
Delete an existing To-Do

You can design this specification to fit your needs however you see fit. For example, you could provide the option to delete one To-Do at a time or several To-Dos in one go. For this, you will need to create resources for your API specification.

You can create a new resource by clicking on the + button next to the RESOURCES section on the left side of the screen. After this, you will be able to see the available HTTP methods that you can configure for your specification (i.e., GET, POST, PUT, PATCH, DELETE, OPTIONS, and HEAD). You can configure each of the methods for a resource, including things like the request/response information, query parameters, headers, and so on.

Screenshot of the /todos resource with one response and no body

For example, if we were to add a successful response to the GET method that returns a list of the existing To-Dos, this is how we would set it up (see screenshot below). In the Responses tab, under the GET method, you just have to click Add New Response to create it and you can click Add Body to add the array of To-Dos under this configuration.

Screenshot of the /todos resource focusing on the properties of the response body

Add URI parameters

When creating the resources for your API, there might come a time when you’d need to make use of URI parameters in your API’s path to pass relevant information like an ID. In the screenshot below, you can see an example of how this configuration would look like. In this case, we are using the URI parameter id to provide a To-Do ID that we will match in the implementation.

Screenshot of URI parameter id for the /todos/{id} resource

As you can see, this is a nested resource. You can create nested resources by clicking on the + button next to the resource you want to add it to. For example, to create this nested resource, you have to click next to the /todos resource.

Conclusion

The API Designer tool further proves how much time you can save by using visual tools that do not require you to learn a lot about a specific tech stack, or that have friendlier learning curves (especially when you are in a rush). In this case, you don’t need to learn the syntax for RAML or OAS to specify an API thanks to the MuleSoft GUI.

MuleSoft continues to advance its product offerings to be faster, more lightweight, and easier to learn/use. And with the new AI boom, who knows what technologies will be available for us in the future?

Further resources

About the author

Alex Martinez was part of the MuleSoft Community before joining MuleSoft as a Developer Advocate. She founded ProstDev to help other professionals learn more about content creation. In her free time, you will find Alex playing Nintendo or Playstation games and writing reviews about them! Follow Alex on LinkedIn or in the Trailblazer Community.