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


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 item

    partially update item

    display allowed verbs on a resource

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


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'


  • 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


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

  • Version media types

  • Custom header
    X-API-Version: 1


  • Using HTTP headers
    Accept-Language: en


Some responses can be cached.

  • Expiration

  • Validation


  • 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