FOSSASIA‘s Open Event Server API documentation is done using an api-blueprint. The API Blueprint language is a format used to describe API in an API blueprint file, where a blueprint file (or a set of files) is such that describes an API using the API Blueprint language. To follow up with the blueprint, an apiary editor is used. This editor is responsible for rendering the API blueprint and printing the result in user readable API documented format. We create the API blueprint manually.
Using API Blueprint:-
We create the API blueprint by first adding the name and metadata for the API we aim to design. This step looks like this :-
FORMAT: V1 HOST: https://api.eventyay.com # Open Event API Server The Open Event API Server # Group Authentication The API uses JWT Authentication to authenticate users to the server. For authentication, you need to be a registered user. Once you have registered yourself as an user, you can send a request to get the access_token.This access_token you need to then use in Authorization header while sending a request in the following manner: `Authorization: JWT <access_token>`
API blueprint starts with the metadata, here FORMAT and HOST are defined metadata. FORMAT keyword specifies the version of API Blueprint . HOST defines the host for the API.
The heading starts with # and the first heading is regarded as the name of the API.
NOTE – Also all the heading starts with one or more # symbol. Each symbol indicates the level of the heading. One # symbol followed by heading serves as the top level i.e. one # = Top Level. Similarly for ## = second level and so on. This is in compliance with normal markdown format.
Following the heading section comes the description of the API. Further, headings are used to break up the description section.
Resource Groups:
—————————–
By using group keyword at the starting of a heading , we create a group of related resources. Just like in below screenshot we have created a Group Users.
# Group Users For using the API you need(mostly) to register as an user. Registering gives you access to all non admin API endpoints. After registration, you need to create your JWT access token to send requests to the API endpoints. | Parameter | Description | Type | Required | |:----------|-------------|------|----------| | `name` | Name of the user | string | - | | `password` | Password of the user | string | **yes** | | `email` | Email of the user | string | **yes** |
Resources:
——————
In the Group Users we have created a resource Users Collection. The heading specifies the URI used to access the resource inside of the square brackets after the heading. We have used here parameters for the resource URI which takes us into how to add parameters to the URI. Below code shows us how to add parameters to the resource URI.
## Users Collection [/v1/users{?page%5bsize%5d,page%5bnumber%5d,sort,filter}] + Parameters + page%5bsize%5d (optional, integer, `10`) - Maximum number of resources in a single paginated response. + page%5bnumber%5d (optional, integer, `2`) - Page number to fetchedfor the paginated response. + sort (optional, string, `email`) - Sort the resources according to the given attribute in ascending order. Append '-' to sort in descending order. + filter(optional, string, ``) - Filter according to the flask-rest-jsonapi filtering system. Please refer: http://flask-rest-jsonapi.readthedocs.io/en/latest/filtering.html for more.
Actions:
————–
An action is specified with a sub-heading inside of a resource as the name of Action, followed by HTTP method inside the square brackets.
Before we get on further, let us discuss what a payload is. A payload is an HTTP transaction message including its discussion and any additional assets such as entity-body validation schema.
There are two payloads inside an Action:
- Request: It is a payload containing one specific HTTP Request, with Headers and an optional body.
- Response: It is a payload containing one HTTP Response.
A payload may have an identifier-a string for a request payload or an HTTP status code for a response payload.
+ Request + Headers Accept: application/vnd.api+json Authorization: JWT <Auth Key> + Response 200 (application/vnd.api+json)
Types of HTTP methods for Actions:
- GET – In this action, we simply send the header data like Accept and Authorization and no body. Along with it we can send some GET parameters like page[size]. There are two cases for GET: List and Detail. For example, if we consider users, a GET for List helps us retrieve information about all users in the response, while Details, helps us retrieve information about a particular user.
The API Blueprint examples implementation of both GET list and detail request and response are as follows.
### List All Users [GET] Get a list of Users. + Request + Headers Accept: application/vnd.api+json Authorization: JWT <Auth Key> + Response 200 (application/vnd.api+json) { "meta": { "count": 2 }, "data": [ { "attributes": { "is-admin": true, "last-name": null, "instagram-url": null,
### Get Details [GET] Get a single user. + Request + Headers Accept: application/vnd.api+json Authorization: JWT <Auth Key> + Response 200 (application/vnd.api+json) { "data": { "attributes": { "is-admin": false, "last-name": "Doe", "instagram-url": "http://instagram.com/instagram",
- POST – In this action, apart from the header information, we also need to send a data. The data must be correct with jsonapi specifications. A POST body data for an users API would look something like this:
### Create User [POST] Create a new user using an email, password and an optional name. + Request (application/vnd.api+json) + Headers Authorization: JWT <Auth Key> + Body { "data": { "attributes": { "email": "example@example.com", "password": "password",
A POST request with this data, would create a new entry in the table and then return in jsonapi format the particular entry that was made into the table along with the id assigned to this new entry.
- PATCH – In this action, we change or update an already existing entry in the database. So It has a header data like all other requests and a body data which is almost similar to POST except that it also needs to mention the id of the entry that we are trying to modify.
### Update User [PATCH] + `id` (integer) - ID of the record to update **(required)** Update a single user by setting the email, email and/or name. Authorized user should be same as user in request body or must be admin. + Request (application/vnd.api+json) + Headers Authorization: JWT <Auth Key> + Body { "data": { "attributes": { "password": "password1", "avatar_url": "http://example1.com/example1.png", "first-name": "Jane", "last-name": "Dough", "details": "example1", "contact": "example1", "facebook-url": "http://facebook.com/facebook1", "twitter-url": "http://twitter.com/twitter1", "instagram-url": "http://instagram.com/instagram1", "google-plus-url": "http://plus.google.com/plus.google1", "thumbnail-image-url": "http://example1.com/example1.png", "small-image-url": "http://example1.com/example1.png", "icon-image-url": "http://example1.com/example1.png" }, "type": "user", "id": "2" } }
Just like in POST, after we have updated our entry, we get back as response the new updated entry in the database.
- DELETE – In this action, we delete an entry from the database. The entry in our case is soft deleted by default. Which means that instead of deleting it from the database, we set the deleted_at column with the time of deletion. For deleting we just need to send header data and send a DELETE request to the proper endpoint. If deleted successfully, we get a response as “Object successfully deleted”.
### Delete User [DELETE] Delete a single user. + Request + Headers Accept: application/vnd.api+json Authorization: JWT <Auth Key> + Response 200 (application/vnd.api+json) { "meta": { "message": "Object successfully deleted" }, "jsonapi": { "version": "1.0" } }
How to check after manually entering all these? We can use the apiary website to render it, or simply use different renderer to do it. How? Checkout for my next blog on apiary and aglio.
Learn more about api blueprint here: https://apiblueprint.org/