Documenting API using API Blueprint

API Blueprint is a great way to document RESTful API. You can use the markdown syntax to describe the API. You can also use MSON to reduce duplication of JSON in the documentation. So a document like this:

FORMAT: 1A
HOST: http://clickplan.apiblueprint.org/

# ClickPlan

This API is used to sell any digital products using a link.

## Products Collection [/products]

### List All Products [GET]

+ Response 200 (application/json)

        [
            {
                "name": "Build a Successful SaaS business",
                "price": "45",
                "thanks_page": "https://www.rubyplus.com/thanks.html",
                "cancel_page": "https://www.rubyplus.com/cancel.html",
                "sales_page": "https://www.rubyplus.com/saas-book.html",
                "created_at": "2015-08-05T08:40:51.620Z",
                "landing_pages": [
                    {
                        "name": "Swift Blog",
                        "link": "http://www.swblog.com"
                    }, {
                        "name": "Python Blog",
                        "link": "http://pythonistas.com"
                    }, {
                        "name": "Objective-C Tutorials",
                        "link": "https://objec.com/tuts.html"
                    }, {
                        "name": "Ruby Blog",
                        "link": "https://rubyplus.net"
                    }
                ]
            }
        ]

### Create a New Product [POST]

You can create a new digital product to sell using this action. It takes a JSON
object containing a product and a collection of landing pages as an array.

+ Request (application/json)

        {
            "name": "Build a Successful SaaS Business",
            "price": "45.95",
            "thanks_page": "https://www.rubyplus.com/thanks.html",
            "cancel_page": "https://www.rubyplus.com/cancel.html",
            "sales_page": "https://www.rubyplus.com/saas-book.html",
                "landing_pages": [
                    {
                        "name": "Swift Blog",
                        "link": "http://www.swblog.com"
                    }, {
                        "name": "Python Blog",
                        "link": "http://pythonistas.com"
                    }, {
                        "name": "Objective-C Tutorials",
                        "link": "https://objec.com/tuts.html"
                    }, {
                        "name": "Ruby Blog",
                        "link": "https://rubyplus.net"
                    }
                ]
        }

+ Response 201 (application/json)

    + Headers

            Location: /products/2

    + Body

            {
                "name": "Build a Successful SaaS Business",
                    "landing_pages": [
                        {
                            "name": "Swift Blog",
                            "link": "http://www.swblog.com"
                        }, 
                        {
                            "name": "Python Blog",
                            "link": "http://pythonistas.com"
                        }, 
                        {
                            "name": "Objective-C Tutorials",
                            "link": "https://objec.com/tuts.html"
                        }, 
                        {
                            "name": "Ruby Blog",
                            "link": "https://rubyplus.net"
                        }
                    ]
            }

# Data Structures

## Product Create (object)

 - name: `Build a Successful SaaS Business` (string, required) - Name of the product
 - price: `45.50` (number, required) - Price of the product in decimal

will become like this:

FORMAT: 1A
HOST: http://clickplan.apiblueprint.org/

# ClickPlan

This API is used to sell any digital products using a link.

# Group Products

## Products Collection [/products]

### Get All Products [GET]

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

### Get an Individual Product [GET /products/{id}]
+ Parameter
    + id: `1` - The ID of the product

+ Response 200 (application/json)
    + Attributes
        - Include Product
        - landing_pages (array[LandingPage])


# Data Structures

## Product (object)

 - id: `1` (number) - The primary key of the product
 - name: `Build a Successful SaaS Business` (string, required) - Name of the product
 - price: `45.50` (number, required) - Price of the product in decimal

## LandingPage (object)

 - id: `1` (number) - The primary key of the landing page
 - name: `Web Developer Blog` (string) - The name of the website
 - link: `http://www.swblog.com/reco.html` - The specific URL of the landing page

To validate the document, you can use apiary. You can signup for a free account at apiary. It also has features to sync your docs with the github repo. It is a two-way synchronization. You can then use tools like aglio to generate the documentation in html format. I demonstrate all the practical aspects of API blueprint in the paid episode on API blueprint, subscribe today for free 30 day access to members only content.


Related Articles


Ace the Technical Interview

  • Easily find the gaps in your knowledge
  • Get customized lessons based on where you are
  • Take consistent action everyday
  • Builtin accountability to keep you on track
  • You will solve bigger problems over time
  • Get the job of your dreams

Take the 30 Day Coding Skills Challenge

Gain confidence to attend the interview

No spam ever. Unsubscribe anytime.