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.

Let’s go ahead and detail what this API document is for;

FORMAT: 1A

# Contacts API Documentation

Documentation for the Contacts API for Acme Company.

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.

FORMAT: 1A

# Contacts API Documentation

Documentation for the Contacts API for Acme Company.

# Group Contact Endpoints

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.

FORMAT: 1A

# Contacts API Documentation

Documentation for the Contacts API for Acme Company.

# Group Contact Endpoints

## Get all contacts [GET /contacts]

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;

## Get all contacts [GET /contacts]

+ Request
    + Headers

            client-id: JuGyFtHx8

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.

FORMAT: 1A

# Contacts API Documentation

Documentation for the Contacts API for Acme Company.

# Group Contact Endpoints

## Get all contacts [GET /contacts]

+ Request
    + Headers

            client-id: JuGyFtHx8

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;

## Get all contacts [GET /contacts]

+ Request
    + Headers

            client-id: JuGyFtHx8

+ Response 200 (application/json)

    [
    {
        "contact_id": 67,
        "firstname": "Harry",
        "lastname": "Johnson",
        "telephone": "+44 123 123 1234",
        "email": "harry.johnson@mydomain.com"
    },
    {
        "contact_id": 32,
        "firstname": "Jane",
        "lastname": "Johnson",
        "telephone": "+44 123 123 1235",
        "email": "jane.johnson@mydomain.com"
    }
    ]

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;

## Get a single contact [GET /contacts/{id}]

+ Parameter
    - id: 67 (number, required) - The id of the contact to return

+ Request
    + Headers

            client-id: JuGyFtHx8

+ Response 200 (application/json)

    {
        "contact_id": 67,
        "firstname": "Harry",
        "lastname": "Johnson",
        "telephone": "+44 123 123 1234",
        "email": "harry.johnson@mydomain.com"
    }

+ Response 404 (application/json)

    {
        "error": "Contact not found." 
    }

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;

## Data Structures

### Contact
- id: 67 (number, required) - The contact id
- firstname: Harry (string, required) - The contacts first name
- lastname: Johnson (string, required) - The contacts last name
- telephone: +44 123 123 1234 (string, required) - The contact telephone number
- email: harry.johnson@mydomain.com (string) - The contact email address

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.

Our next endpoint will allow the adding of a new contact;

## Add a new contact [POST /contact]

+ Request (application/json)

+ Request + Headers client-id: JuGyFtHx8

+ Attributes - firstname: Harry (string, required) - The contacts first name - lastname: Johnson (string, required) - The contacts last name - telephone: +44 123 123 1234 (string, required) - The contact telephone number - email: harry.johnson@mydomain.com (string) - The contact email address + Response 200 (application/json) + Attributes (Contact) + Response 400 (application/json) { "error": "Required fields missing or Contact already exists." }

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;

## Edit an existing contact [PUT /contact/{id}]

+ Parameter
    - id: 67 (number, required) - The id of the contact to amend

+ Request 
    + Headers 

            client-id: JuGyFtHx8

+ Request (application/json) + Attributes - firstname: Harry (string, required) - The contacts first name - lastname: Johnson (string, required) - The contacts last name - telephone: +44 123 123 1234 (string, required) - The contact telephone number - email: harry.johnson@mydomain.com (string) - The contact email address + Response 200 (application/json) + Attributes (Contact) + Response 400 (application/json) { "error": "Required fields missing." }

You can see, it’s very similar to adding a new contact, but the URI includes an ‘id’ parameter and we’ve set the request type to ‘PUT’.

Finally, let’s have an endpoint to delete a contact;

## Delete a contact [DELETE /contact/{id}]

+ Parameter
    - id: 67 (number, required) - The id of the contact to delete

+ Request 
    + Headers
    
            client-id: JuGyFtHx8

+ Response 200 (application/json) { "message": "Contact deleted." } + Response 404 (application/json) { "error": "Contact not found." }

Comments

There are no comments, why not be the first?

Submit a reply

Your e-mail address will not be published, all fields are required.