Skip to content

Instantly share code, notes, and snippets.

Forked from joyrexus/
Last active Aug 29, 2015
What would you like to do?
REST basics

Basics of RESTful API design

  • Your API should be designed around the idea of resources.

  • Resources represent things (nouns) and not behaviors (verbs).

  • Each resource should have a canonical/unique url (api/users/bill, api/users/mary).

  • Return all resource properties in the return payload.

  • HTTP methods (GET, PUT, etc.) represent behaviors on your resources.

  • Instance resources (/api/users/bob) should be represented as a child of some parent collection resource (/api/users).

  • Collections are themselves resources with their own properties.

  • Collections should support both create and query requests.

  • Instance resources should support read, update, and delete operations.


Suppose the base URI of our API is


We'll represent the set of all Acme users with a user collection resource (/users) and handle any incoming http requests to on the basis of the request method:

  • GET - return a list of URIs for the user instance resources in this collection.

  • PUT - replace the entire collection with a new set of users.

  • POST - create a new user and returning the new user's unique resource URI.

  • DELETE - delete the collection of users.


We'll represent an Acme user (e.g., "Bob") with a user instance resource (/users/bob) and handle any incoming http requests to on the basis of the request method:

  • GET - return a representation of the user (e.g., a JSON-encoded data structure containing info about the user).

  • PUT - replace the user at the specified URI or create if they don't yet exist. (Note that you typically want to create new users with a POST method on the collection.)

  • POST - this method is not typically utilized on an instance resource, but if you're representing individual users as sub-collections (say, collections of individual responsibilities, each represented as instance resources) then you would handle the request by creating a new entry. For example, if sending a POST request to /users/bob with info about Bob's responsibility to care for the chickens you might return and instance resource URI like /users/bob/chickens, etc.

  • DELETE - delete the user.


There are numerous tutorials on the web that will walk you through building a basic REST API. If you're comfortable using node, the following two articles cover the basics using two widely-used node frameworks:

  • express - utilizes Express 4 and MongoDB.

  • restify - utilizes Restify and implements an OAuth2 client credential workflow with a helper library, nicely overviewing how you might go about authenticating your API; also walks you through developing a simple client for the API.

If you'd rather develop your REST APIs using Go (recommended!), try:

  • json api - nice step-by-step walkthrough.

  • how i start - works through building a backend service proving weather data.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment