-
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 http://acme.org/api
.
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.
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 aPOST
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 aPOST
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.