HTTP and REST are not new, we just misused them for a long time. A proper RESTful API should consider the following principles.

Resources

Resources are discrete entities - like entities from the Entity-Relationship Model. The web is modeled around resources. Everything is a resource, not a web page, not an application. Resource names should be intuitive and should be nouns. Avoid Verbs in URLs.

/resource

represents a collection of items

/resource/id

represents an individual item

/users/1/address

Resources can be nested in order to reflect the relationship between them.

Querystring parameters

In order to filter, order, limit or offset resource entries we should not create separate sub-resources. Here’s where querystring parameters come into play.

/addressbook?orderby=lastname

/users/1/vehicles?filter=bikes

HTTP Methods (Verbs)

The HTTP Verbs operate on resources. Resources can be queried and altered using Verbs. Some operations are idempotent.

GET

read item / collection of items

nullipotent – does not modify state, no side effects

POST

create new item alters state each time it is called

PUT

update item

idempotent – calling it multiple times has the same effect as the first time

DELETE

delete item

idempotent

PATCH

partially update item

idempotent

OPTIONS

display allowed verbs on a resource

nullipotent

How verbs operate on resources

Example scenario:

/resource

GET collection of items

POST create new item

PUT update collection of items – this is rarely used since it updates the whole collection

DELETE collection of items

OPTIONS could display a quick help on how to query the resource

/resource/id

GET item

POST - using POST to create an item at an unexisting resource id is a nono

PUT (sometimes POST) update item

DELETE item

Responses

Give a proper response after each request. Applications can be much easier to develop if they get meaningful response codes.

after GET

respond 200 ‘OK’ (default)

body with item

after POST (create)

respond 201 ‘Created’

location: /resource/id of created item

body with created item

after PUT/POST (update)

respond 200 ‘OK’

body with updated item

after DELETE

respond 204 ‘No Content’

empty body

after a bad request/unallowed method

respond 400 ‘Bad Request’

empty body

after encountering a problem on the server side, like a failed SQL query

respond 500 ‘Internal Server Error’

Hypermedia

Self describing API

Each response should provide links to explore the API .

Just like HTML connects multiple pages through links, API responses should have links to other resources.

Ideally, an API could be explored entirely without prior knowledge of its resources, just by knowing its base URL .

Content negotiation

Using HTTP headers

Accept: application/json, text/plain

Extension in the URL

Not RESTful, URLs are not the place for Content-Type

Versioning

Version in the URL /v2/resource Create separate resources for a new version of the API.

Version media types

application/vnd.something.v1+json

Custom header

X-API-Version: 1

Language

Using HTTP headers

Accept-Language: en

Cache

Some responses can be cached.

Expiration

Cache-Control

Expires

Validation

Last-Modified

ETag

Authentication

OAuth

Industry standard. Used by most services.

HTTP Auth

Part of the HTTP standard. Digest auth uses hashing and a nonce.

Cookies

Can be used for login similar to classic web applications.

Also Read