REST basics

README.md

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.

Example

Suppose the base URI of our API is http://acme.org/api.

/users

We'll represent the set of all Acme users with a user collection resource (/users) and handle any incoming http requests to http://acme.org/api/users 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.

/users/{id}

We'll represent an Acme user (e.g., "Bob") with a user instance resource (/users/bob) and handle any incoming http requests to http://acme.org/api/users/bob 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.

tutorials.md

Tutorials

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.