Creating our first document

Open Atom, and create a new file, for the sake of this tutorial we’ll call the file docs.apib. API Blueprint files use the file extension .apib

The first thing we need to put into our document is some metadata to define what version of API Blueprint we’ll be using in the document. Then we give our document a main title.

FORMAT: 1A
# Contacts API Documentation

At this point, you can view a preview of your API documentation by pressing ‘ctrl-shift-a’ while viewing your document in Atom. This will open a preview window, and it is you should see the title of your document. It may not look like much for now, but don't worry we'll build on this.

What we’re going to next is add a group labelled ‘Contact Endpoints’. This group essentially groups the following resource definitions. In our case, all endpoints relating to a contact will be in this group.

Lets create our first resource for the URI /contacts. In our mock API this URI would return a list of all contacts held in the API. The only parameter it will accept is a client-id in the request headers. The client id in our API ensures that our end points can't be directly accessed without a valid client id.

Hopefully the above markup should be pretty self explanatory. We’ve added one line which defines the resource, we’ve given the resource a name, request method and finally the URI of the endpoint, in this case /contacts. Next lets describe the request;

At this point it’s worth noting that API Blueprint is very particular with text tabulation. Tabs must be 4 spaces, and parts of your document need to be correctly tabulated for the parser to successfully parse your document. If you parse your document directly using Aglio it indicate if you have any errors in your document. To generate HTML output of your document simply run the following command from the command line;

$ aglio -i docs.apib -o output.html

This should generate an ouput.html which you can view in a browser, it uses the default Aglio template, but you can select to use other templates so it’s worth while checking out the documentation for Aglio.

You can see above we’ve defined a request using ‘+ Request’, below that we’ve defined a headers section, and beneath that we’ve added our ‘client-id’ along with an example of what a client-id should look like. Remember, don't publish your real client id in your documentation. Remember to put a new line after '+ Headers' and the start of your header elements or Aglio will through some errors.

The preview of your document should look something like this;

Now we know what the request will look like, let’s go ahead and build the response;

We’ve defined a response with ‘+ Response’, after that is the expected response status code, and finally we describe the type of document we’ll be returning, in this case JSON (application/json). Below the response definition we’ve placed a JSON response to show what type of response you should expect from this endpoint.

Our next endpoint will return only a single contact, specified by it’s contact_id, so this time our URI will contain a URI parameter;

The first thing you’ll notice is the parameter in the URI ‘/contacts/{id}’, below this we’ve provided some information about what the ‘id’ parameter’s value should be, in this case we’ve given it the name ‘id’, and an example value of ’67’, we’ve then said it should be a number and it’s required. Finally we’ve provided a description for the parameter.

The 200 response only returns a single contact, and you’ll notice we also have a second response with a status code of 400. Yes, you can define multiple responses, this is especially useful if you’re going to be returning errors, in our case we’re returning a 404 error with a JSON object to describe the problem, in our case ‘Contact not found.’.

Data Structures

You’ll notice that so far we have in our document three contacts, and as we develop our document further we’re going to be adding more contact objects. To avoid copying and pasting JSON we can use data structures to define a single object and re-use this within our document.

At the bottom of your document, let’s create a data structure for a contact;

We’ve added a Data Structures section, all of our data structures should be placed below this line. Our first data structure is a contact, and you’ll see above it clearly describes a contact and matches the contact JSON object we’ve been returning in responses so far. The benefit of this data structure is that we can now use this in our requests and responses without repeating ourselves.

Change the 200 response for the URI ‘/contacts/{id}’ to this;

+ Response 200 (application/json)
+ Attributes (Contact)

Our response now contains an ‘Attributes’ element, and following it is (‘Contact’). The attributes element allows us to describe a response, and have the response converted to JSON (or even XML) depending on the response document type, we’re using ‘application/json’ so our response will be converted to JSON when parsed. If you check the preview your response should be in JSON format.

Let’s go ahead and do the same with the ‘/contacts’ endpoint, change the response to;

+ Response 200 (application/json)
+ Attributes (array[Contact])

The response is almost the same as the previous response we amended, but with one minor difference, instead of ‘Attributes (Contact)’ we’ve said that the response will return an array of Contacts, ‘(array[Contact]). If you look at the preview you will see that the response only contains one JSON object, but you can clearly tell from the resulting JSON that the response is an array.

We can see from the above that the endpoint expects the request to be in JSON format, and in the attributes section we’ve defined the individual attributes that it’s expecting you to pass in the body of the request. We didn’t use our Contact data structure as we needed to exclude the ‘id’ field.

Using what we’ve learn in the above steps, let’s go ahead and create the endpoint to allow us to edit an existing contact;