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 also must be a lot painful if you are maintaining this project yourself over time. I have also been through such a situation myself.

Luckily, there are a 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 to such a few standards. This article is aimed at web developers, who are just getting started and wondering how to begin with their REST API documentation or people who already have an API project, but haven’t documented it yet.

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

1. Why you should have your REST API documented
2. What different choices do 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 project, 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, it’s recommended to do minimal documentation. Such as, commenting on 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 behaviours.

But, it’s not the same case if you are writing 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 things that apply to your whole application, such as headers, auth tokens, etc. Without proper documentation/examples, it could take you a while to set up an example API request in your local development environment with an existing API project that is new to you.

Here are a few more points that you might want to learn about as well:

• Understandability: It will help other team members/developers/testers to understand very quickly and clearly. It explains what this API is about, what the request/response types are, what parameters it requires/accepts, etc.
• Maintainability: If you are planning for a project with a long-term commitment, it’s a must that you should have its details documented and maintained for future reference.
• API Versioning: If you maintain a well-documented API, creating a new version of the API, separately documented with the new version specified and legacy support old version of the API
• Tools Support: Many REST API tools will support specifications written in standard well-known formats(including generating 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 a dependency with any other component or if something’s missing, etc.

So, hope you are now convinced and ready to write some API specifications. Let’s move ahead!

What Tool Can You Use To Document Your API?

As I mentioned in the beginning, the standards currently available are still relatively young. However, several documentation standards have become widely popular in the 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 the most widely used. Correct me, if I am wrong.

• Swagger: This is the most popular and my favourite format. You can design and make your REST API documentation in a very elegant way with the greatest possible integrated support of various fields/types. It also supports providing custom field types via extension fields(using the ‘x-{your-field}’ format). It also allows you to write specifications in both YAML and JSON formats.
• RAML: It is also a very popular format. It features a tree structure for your REST API. So, you, as a developer, are more encouraged to write API specs in a better, more meaningful way, which helps you avoid writing conflicting APIs. 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 a cons, it allows you to write the specs in YAML format only. I also noticed it is lagging behind some important primitive types for specifying parameters, such as ‘array’.
• API Blueprint: So, I haven’t dug this format much, but it’s pretty popular too and you might want to check it out as well. Who knows, it might be your favourite!

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

An Example Documentation:

As we now know what we can use for documentation, let’s see a very simple example of API specification documentation in swagger format. Swagger supports both JSON and YAML.

Let’s see the YAML format one:

swagger: '2.0'
info:
  version: 1.0.0
  title: Simple example API
  description: An API to illustrate Swagger
paths:
  /list:
    get:
      description: Returns a list of stuff              
      responses:
        200:
          description: Successful response 
Code language: YAML (yaml)

As you can see above, you can specify your API project’s name/version/description as an overview. Also, you can specify the host and base path for your API. Then, for each endpoint, 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 and are probably excited to try writing your first REST API documentation yourself! These are really going to make your API workflow life easier. To store, maintain, and distribute it among the team with a lot of efficiency! There are a lot of developer tooling platforms which support these formats and enable you to integrate with them seamlessly. I will share about those as well. But that’s for another day. Happy coding 🙂