CodeSamplez

Programming and web development blogs

  • Facebook
  • Google+
  • RSS
  • Twitter
  • Home
  • Featured
    • C# Tutorials
      • LinQ Tutorials
      • Facebook C# API Tutorials
    • PHP Tutorials
      • CodeIgniter Tutorials
    • Amazon AWS Tutorials
  • Categories
    • Programming
    • Development
    • Database
    • Web Server
    • Source Control
    • Management
    • Project
  • About
  • Write
  • Contact
Home Development Document Your REST API Like A Pro

Document Your REST API Like A Pro

Rana Ahsan January 26, 2016 1 Comment


 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 🙂

Share If Liked

  • Click to share on Facebook (Opens in new window)
  • Click to share on Twitter (Opens in new window)
  • Click to share on LinkedIn (Opens in new window)
  • Click to share on Pinterest (Opens in new window)
  • Click to share on Reddit (Opens in new window)
  • Click to share on Tumblr (Opens in new window)
  • Click to share on Pocket (Opens in new window)

Filed Under: Development Tagged With: api, documentation, rest

About Rana Ahsan

Rana is a passionate software engineer/Technology Enthusiast.
Github: ranacseruet

Comments

  1. Ewout Van Gossum (@DenEwout) says

    January 27, 2016 at 3:55 am

    These are mostly specifications, as you say in your conclusion, there are many tools available for these specs. Tools that generate documentation automatically (by parsing source code), or that help you write your documentation from scratch (api designers). I’m looking forward to your next post.

    Reply

Leave a Reply Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Email Subscription

Never miss any programming tutorial again.

Popular Tutorials

  • Generate HTTP Requests using c#
  • How To Work With JSON In Node.js / JavaScript
  • How To Work With C# Serial Port Communication
  • PHP HTML5 Video Streaming Tutorial
  • LinQ To SQL Database Update Operations In C#
  • Facebook C# API Tutorials
  • Control HTML5 Audio With Jquery
  • Get Facebook C# Api Access Token
  • How To Work With Multithreaded Programming In C#.NET Application
  • LinQ Query With Like Operator
Follow Us On Twitter

Recent Tutorials

  • Document Your REST API Like A Pro
  • Understanding Golang Error Handling
  • Web Application Case Studies You Must Read
  • Getting Started With Golang Unit Testing
  • Getting Started With Big Data Analytics Pipeline
  • NodeJS Tips And Tricks For Beginners
  • Apple Push Notification Backend In NodeJS
  • Web Based Universal Language Translator, Voice/Text Messaging App
  • How To Dockerize A Multi-Container App From Scratch
  • Getting Started With NVML Python API

Recent Comments

  • Chris on PHP HTML5 Video Streaming Tutorial
  • Alain on PHP HTML5 Video Streaming Tutorial
  • waail on How To Work With C# Serial Port Communication
  • pakdhetimin on Few Useful Smarty Examples And Tips
  • virender on Getting Started With CodeIgniter URL Routing

Archives

Resources

  • CodeSamplez.com Demo

Tags

.net apache api audio aws c# cache cloud server codeigniter deployment doctrine facebook git github golang htaccess html5 http image java javascript linq mysql nodejs oop performance php phpmyadmin plugin process python regular expression scalability server smarty ssh tfs thread tips ubuntu unit-test utility web application wordpress wpf

Copyright © 2010 - 2019 · CodeSamplez.com ·

Copyright © 2019 · Streamline Pro Theme on Genesis Framework · WordPress · Log in