Feb 20, 2018
5 minutes to read
Note: we are going to talk about JSON APIs specification. It does not deal with other APIs format such as XML APIs.
At FABERNOVEL TECHNOLOGIES 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!
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:
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:
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.
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 ressources 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.
Finally for your project you have defined all the routes in detail:
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!
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?
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.
To find correct and updated information, PERICLES allows to create list of resources with their attributes, routes and resource representations used in each route.
To test API request and responses, PERICLES contains a proxy tool that permits to validate every response of the API against the representation of the corresponding route.
To mock, PERICLES may automatically generate JSON examples thanks to information defined.
Now with PERICLES:
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/applidium/PERICLES
Want to know more about APIs spécification?Contact Julie