REST API Properties

gistfile1.txt

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.