Document Your REST API Like A Pro

You are a web application developer and trying hard to build robust, scale-able RESTful API. However, you are not documenting your API structure/skeleton at all. Hello! you are doing it wrong! It’s also must be a lot painful if you are maintaining this project yourself over time. I have been through such situation myself also.

Luckily, there are few REST API specification standards released over the last few years which are totally awesome. And totally worth the effort/time to write. I am going to introduce you today with such few standards. This article aimed to web developers, who are just getting started and wondering how to begin with their REST API documentation or people who are already have an API project, but haven’t documented yet.

Just a heads up, I am going to cover these following areas in a nutshell:

1. Why you should have your REST API documented
2. What different choices you have
3. How To Document API specification With Example

So, without making you bored with unrelated chit-chatting any further, let’s get to the points!

Why REST API Documentation?

Well, if you ask me this, I will simply ask you, why not?

For any kind of projects, it’s a must. Am I right? Of course, in agile development, we sometimes skip the major boring documentation parts(Such as SRS etc). But still, even in such cases, its recommended to do the minimal documentation. Such as, commenting your functions/classes to explain what they are/what they do etc. For traditional source codes, this is enough to understand the input/output and behaviors.

But, it’s not the same case if you are writing an REST API endpoints. From the source code, even though you might understand the business logic, it doesn’t help with the input/out formats much. Besides, there are several staffs which applies to your whole applications, such as headers, auth tokens etc. Without having proper documentation/example, it could take you a while to set up an example API request in your local development environment with an existing API project, which is new to you.

Here are few more points, which you might want to learn about as well:

• Understandibility: It will help other team members/developers/testers to understand very quickly and clearly. It explains what this API is about, what are the request/response types, what parameters it requires/accepts etc.
• Maintainability: If you are planning for a project with long-term commitment, it’s a must that you should have its details documented and maintained for future references.
• API Versioning: If you maintain well documented API, creating new version of the API, separately documented with new version specified and legacy support old version of API
• Tools Support: Many REST API tools will support specifications written in standard well-known formats(including generate the specification docs as well!) and you can leverage their support on your API.
• Outline: You shouldn’t only document your API, but you should do it first, even before any implementation code. Because, in the process of documenting, you will outline how the API is going to work, is their dependency with any other component or if something’s missing, etc.

So, hope you are now convinced and ready to write some API specifications, lets move ahead!

What Tool You Can Use To Document Your API?

As I mentioned in the beginning, currently available standards are still relatively young. However, yet several documentation standards become widely popular in last two/three years. Which also proves how much they were wanted by developers. I am going to list the top three I have in mind at this moment. I believe these are most widely used. Correct me, if I am wrong.

• Swagger: This is most popular and my most favorite format. You can design and make your REST API documentation in a very elegant way with greatest possible integrated support of various fields/types. It also has support for providing your own custom field types via extension fields(using ‘x-{your-field}’ format). And it allows you to write specifications in both YAML and JSON format.
• RAML: It is also very popular format. It features tree structure for your REST API. So that, you, as a developer are more encouraged to write API spec in a better meaningful way and help you avoid writing conflicting API. For example, if you are developing different endpoints like ‘/product/{something}’, ‘/product/{something-else}’ etc which aren’t very related to ‘product’, you will be able to catch up and fix easily as it will have a generic description for ‘/product’ uri and others will be nested.

  As cons, it allows you to write the specs in YAML format only. I also noticed it lagging some important primitive types for specifying parameters, such as ‘array’.

• API Blueprint: So, I haven’t really digg this format much, but its pretty popular too and you might want to check it out as well. Who knows, it might be your favorite!

You will also might want to try out with Google’s format, io docs, WADL as well.

An Example Documentation:

As we now know what we can use for documentations, lets see a very simple example of API specification documentation in swagger format. Swagger supports both json and YAML.

Lets see the yaml format one:

swagger: '2.0'
info:
  version: '1.0'
  title: My Product API
  description: |-
    Description for my product API in brief
paths:
  /products:
    parameters: []
    get:
      responses:
        '200':
          description: ''
          schema:
            type: object
            properties:
              name:
                type: string
              id:
                type: string
              description:
                type: string
      parameters: []
      consumes:
        - 'application/json'
      produces: 
        - 'application/json'
      operationId: 'GET_products'
      summary: ''
definitions: {}
basePath: ''
host: 'http://localhost:3000'

As you can see above, you can specify your API project’s name/version/descriptions as overview. Also, you can specify host and base path for your api. Then, for each endpoints, you can specify its supported types, request/response formats, additional uri/query-string or header parameters etc.

There are plenty of other fields and features supported in swagger, which you can learn about on their official specification documentation page.

Conclusion:

I hope you enjoyed the article so far and probably excited to try writing your first REST API documentation yourself! These are really gonna make your API workflow life easier. To store, maintain and distribute it among the team with a lot efficiency! There are a lot of developer tooling platforms which supports these formats and enables you to integrate with them seamlessly. I will share about those as well. But that’s for another day. Happy coding 🙂