There are two common workflows followed by software engineers developing RESTful API's: the Specification-first approach; and the Implementation-first approach.

The Specification-first approach

The OpenAPI specification (formerly known as the Swagger specification) is the most popular and widely adopted specification for RESTful APIs. And, there are a great many tools, libraries and frameworks that support the OpenAPI/Swagger ecosystem.

Generator for OpenAPI

Rebilly's OpenAPI generator is designed to kickstart your specification-first RESTful API design workflow.

There are only a few steps you need to follow:

  • Install a Node.js distribution, for example:

    Add the NodeSource APT generator for Node 6:

    curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash

    Install Node.js:

    sudo apt-get install -y nodejs

  • Install Yeoman and generator-openapi-repo:

    sudo npm install -g yo generator-openapi-repo

  • Create the GitHub repo where your OpenAPI specification will live.

  • Clone your repo and then run the following command:

    sudo yo openapi-repo

  • Commit and push your changes to GitHub:

    git add .
git commit -m "Initial commit"
git push origin master

I followed the specification-first RESTful API design workflow when creating this specification:

get-individuals

The OpenAPI generator provides out-of-the-box support for ReDoc (and swagger-ui), swagger-editor, Travis (CI) and GitHub pages.

The OpenAPI Specification

If your new to the OpenAPI/Swagger specification then you should take a look at Arnaud Lauret's posts.

Fake it before you make it: JSON Server

The call to action says it all:

Get a full fake REST API with zero coding in less than 30 seconds!

json-server let's you mock your API using JSON:

{
  "posts": [
    { "id": 1, "title": "json-server", "author": "typicode" }
  ],
  "comments": [
    { "id": 1, "body": "A comment", "postId": 1 }
  ],
  "profile": { "name": "typicode" }
}

Start JSON Server:

json-server --watch my-api.json

Now, if you navigate to: http://localhost:3000/posts/1, you'll GET:

{ "id": 1, "title": "json-server", "author": "typicode" }

Generate code snippets

You can use Postman to generate code snippets in more than 15 languages.

The Implementation-first approach

I've discussed the implementation-first approach in several posts:

References: