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
.
/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.