How to build perfect RESTful APIs specification?

We, at Fabernovel, consider that a complete API project specification should allow to: find correct and updated information such as resources, routes and the way they should be used; test API requests and responses; make relevant examples through mocks for frontend developers. So what we are going to introduce here is how to easily maintain an API specification with better documentation, relevant mocks and facilitated tests.

Note: we are going to talk about JSON APIs specification. It does not deal with other APIs format such as XML APIs.

Frontend crashes because of APIs…

At Fabernovel we develop mobile and IoT apps, chatbots, web applications and many more digital products. Hence, we deal with JSON APIs all day long: as consumers for frontend developments and as producers for backend developments. APIs are in our daily activities: they are ubiquitous in our work and come along with many issues we are not the only ones to face.

Today when there is a frontend crash, the Quality Assurance (QA) team or the developer are going to spend a lot of time debugging and understanding why. When they find the source of the crash, it’s often because the API specification they had for the development does not match the current response.

No kidding. It happens like… all the time!

It’s time for a change!

Until now we used plenty of great solutions to help us manage our APIs. The Product Owner used Slate, Word or Swagger to document, developers used Wiremock as a mocking tool and QA team used Postman to test.

But in the end all these solutions ended up desynchronized. Product owner, developers and QA team were wondering all the time where the truth resided.

A crash occurred, the Product Owner was unsatisfied, developers and QA team lost their time, all because of a desynchronization problem.

Never again! We decided to find a tool to become the single source of truth and specify APIs.

At this point we had three options:

1. Find one tool to rule them all: documentation, mocks and tests. But after a deep market research we did not find something that fit all our requirements meaning easy testing, easy documentation and easy mocking.
2. Synchronize different tools. But this is highly dependent on what the solutions allow to import or export: the communication between the different tools may evolve and sometimes may be broken. It’s tedious to follow and to maintain.
3. Build our own solution.

As we did not find a satisfying solution on the market we chose to create our own solution. Our teams love to design and develop products so it was not such a painful decision.

On our way to build a powerful tool to specify JSON APIs, we started solving the simplest problem we could find: uniquely specifying one JSON.

Is a JSON correct?

To specify a JSON (in a request or in a response for example) you can use a JSON Schema.

A JSON Schema is a format that defines a JSON structure: the fields and their primitive types (String, Integer, Boolean, etc.), the required fields and the optional fields, etc.

Such JSON Schema allows you to:

• Document : you can describe all keys and values in the schema;
• Test : you can validate any JSON against the schema;
• Mock : you can generate a valid JSON against this schema.

With a JSON schema Product Owner, QA team and developers have a first single common ground to discuss.

Let’s see how you can expand such concept to a whole projet.

How to expand JSON schema concept to RESTful API level?

Define your project resources

When you have to specify a RESTFul APIs project first you need to identify the resources you will use in your API: a user for example.

For each resource you define the attributes; for our user: a first name, a last name and an age.

Define your project routes

Now that resources are defined with their attributes, it is time to manipulate them. But how could we create, consult information about, update or even delete users?

All available actions on your resources will form your collection of routes.

For each route we will define how it is used: URL, HTTP method, parameters header, input body (which is a JSON schema!), and how it responds (another JSON Schema!)

Working with resources representations

Your resource may be more complex than just a three attributes object, and you may want to have different levels of information.

To create a new user, you may only want to send two attributes like first name and last name in the request body. But to display user’s profile all attributes are needed, so you would like to get them all.

These different levels of information represent your different resource representations.

And as you can see in the two following examples, your routes are linked to resource representations, not the resource itself.

User may be seen as an object with two attributes - User creation - or as an object with three attributes - User detail. But it is always the same object, we only represent it in two different ways.

We use such JSON schema to validate requests AND responses.

And done!

Finally for your project you have defined all the routes in detail:

• URL, HTTP method, GET parameters, headers
• Unique request or response JSON body thanks to ressources representation and the associated JSON Schema.

With all routes very well defined you will have a strong and clear RESTFul APIs project specification. Now we have the entire API documentation without any ambiguity!

Abstract JSON Schema complexity

JSON Schema is a powerful concept to specify a whole API project…except it is really tedious to write. It would have been insane (and absolutely boring) for all our Product Owners, Developers or QA team to write by hands theses schemas.

So we wanted to abstract this complexity and ease Product Owners, Developers or QA team in their everyday life.

No need to prolong the suspense any longer, let’s introduce PERICLES!

At first PERICLES was the internal code name used for an internship topic. But given the growing need to have a centralized tool to share all API specification we deepened the subject. PERICLES was also a Greek statesman, orator and general of Athens during the Golden Age. Inspiring, isn’t it?

What can you do with PERICLES?

As we explained before a trustful API specification enables to find correct and updated information, to test API requests and responses and to mock. The cornerstone of API specification is JSON Schema: it’s the basis to define the single source of truth.

Before PERICLES:

• The QA team spent hours trying to replay a use case when the frontend crashes
• The developers had to update hundred of files in documentation and mocks
• The Product Owner did not know where was the truthful information regarding the APIs documentation…

Now with PERICLES:

• The QA team only has to read a report to see where there may be something wrong in the API thanks to a proxy
• The developers should only update information in one place
• The Product Owner has a truthful source of documentation.

What’s come next?

PERICLES automatically generates the mapper for your frontend applications, automates tests of your endpoints, and provides a truthful documentation. This tool is not yet a product. It’s an internal solution used for specifications of APIs we build or consume. But we are longing to improve it!

To see how PERICLES looks like today please visit our Github and deploy your own PERICLES instance - with a nice “Deploy to HEROKU” button. If you are interested in making suggestions: feel free! You will be our guest ;)

It’s over there: https://github.com/faberNovel/pericles.