How to design and mock an API visually

Why designing your APIs first is a crucial component of the software development process and how to mock them visually in Martini.

APIs are the primary gateway to software applications and online services which is why you should put them first when it comes to software development. So, let’s delve into this and learn why designing your APIs before implementing them is so important, the different approaches to this process, why you should mock them, and how to do it with Martini.

Let’s get started!

In the code-first development approach, developers are in charge of designing and implementing all APIs based on the features an application should have. This means that the consumers and other stakeholders of the API aren’t involved in the design process. This increases the risk of delivering an application that doesn't meet their needs.

Since APIs are typically the most crucial part of an application, you should give them more importance. That’s why the API-first approach has become one of the most popular design strategies for software development. 

With API-first, the development team collaborates with all of the stakeholders of the API to make sure that it meets their requirements through an iterative feedback loop. This way, by the time you start implementing the API you can be confident that it is going to meet the requirements of the consumers of the API and it is more likely to be adopted by them. Note that the implementation of the API will commence only after this design process is complete.

This strategy can save you time and money, but it only works if you know how to design APIs properly.  So, let's delve into the most common approaches to API design.

Designing an API means defining the API's paths, methods, inputs and outputs, and formats. The traditional approach to API design involves a text editor or a documentation tool. On the contrary, visual API design is about using a visual, advanced, drag-and-drop editor.

There are 3 main differences between these approaches:

1. Users: traditional API design is based on tools that only a developer can use, while visual API design requires an intelligent visual editor accessible to everyone.

2. Workflow: a visual tool inherently guides you throughout the API design process, while a text editor or documentation tool offers no guided workflow.

3. Feedback: a visual editor provides you with immediate and visual feedback, something that a traditional API design tool can’t offer.

When collaborating with stakeholders some decisions are going to be made about the type and properties of a response to each request. Now, let’s review a popular strategy when it comes to enabling stakeholders to test against the proposed design which is often referred to as "mocking an API".

What mocking an API is and why it is so important

Mocking an API involves creating an API that imitates the behavior of the proposed API without actually implementing the APIs services. In other words, a mock server acts like a real server and consists of APIs missing business logic but providing realistic responses to requests. So, these mock APIs simulate the behavior the real APIs should have. Their response can be static or dynamic. In the first case, the response is hard-coded into the API logic. In the second case, the mock API returns predefined responses based on some expected parameters.

As you can imagine, mocking APIs is a critical part of the API-first methodology presented above. This is because API-first is about iterating over the design process with the stakeholders that will be consuming the APIs. And by mocking them, the stakeholders can experiment with the APIs immediately. In fact, mocking APIs is a quick process that involves little effort. This way, the stakeholders can use the mock APIs to see if they return the data they need and give feedback about them.

That’s why API mocking is so crucial, and also why you need the right tool to implement it. So, let’s see how a visual tool such as Martini can help you mock an API.

Designing and mocking an API visually with Martini

Let’s see how to design and mock a GET API in Martini with a step-by-step guide.

If you haven’t installed Martini yet, get it here and follow the installation procedure. Then, launch Martini. For purposes of this demo we will be using Martini Desktop but the process is the same if you are using Martini Online.

This is what an "empty" instance of Martini looks like:

Now, you need to create a package that will containing your API. Let’s call it “mock-apis”. You can do this with the following 3 steps:

1. right-click on local under the Navigator tab

2. New > Package

3. In the popup window, enter “mock-apis” in the Name field and click Finish

Now, add an API to your package. Let’s call it “Contacts” and add it as explained below:

1. right-click on the code folder under “mock-apis” in the Navigator tab

2. New > Create API

3. In the popup window, enter “Contacts” in Name field, select Type = "REST API", and click on Finish

You have just created a blank API, but you need to associate a path to it. Double-click on Contacts and then press “Add Path”. Let’s define it as v1/contacts.

Now, define a GET operation by right-clicking the Operations field under the Contacts tab and clicking on New Operation > GET. 

Here is what your API should now look like, notice how the design is in a logical tree hierarchy with the path defined at the top of the tree and the operations and properties of each path thereunder: :

Let’s now create an empty service that will serve as a placeholder for this operation by right-clicking on the Service field and then on Edit. Then, click on the “…” button under the Value column and press "New…" in the following popup window.

Create a new service called GetContacts and press Finish. Note we won't actually be implementing this service until after the design process has finished. But the service acts as a placeholder and enables us to define a mock response for the operation instead.

To make your API work, you need to add a response. You can do it as follows:

1. right-click on the Responses field

2. select "New Response"

3. Select “200 (OK)” as status and press “Next >” to define the body 

Add a contacts property of type Model to the body response and press Finish

Now, set the Mock property to true and you should then be able to access the "Body Mock Data" field. To define the response of your mock API, double-click on the Value column on "Body Mock Data", press the “…” button, paste your JSON response in the popup window, and press OK.

It is now time to see it in action but before doing so, make sure to save your progress by clicking the save button. 

In Martini Desktop, you can test your API by right-clicking Contacts under local > mock-apis > Contacts and selecting "Invoke in HTTP Client". If you are using Martini Online you can also use any other HTTP client such as Postman to invoke the service. You can download a Postman collection for your API under the Preview tab.

The API operation will open in the HTTP client with the method and path already set. You can see the HTTP client in the bottom window of the screen shot below:

Press Send and you should be able to see the JSON you entered in the Mock step above in the Response tab.

Et voilà! You just created an API that returns 200 and responds at the v1/contacts endpoint with the JSON mock response you defined previously!

Conclusion

In this article, we learned why designing an API is so important, especially when it comes to adopting an API-first strategy to development. This can be done in many ways, but mocking it by employing a visual tool is one of the best approaches. And here we learned how easy and effective it is to design and mock an API visually with Martini.