The Richardson Maturity Model outlines three levels of REST API maturity that make it RESTful. Level 1 is characterized by the use of URI resources and HTTP methods. Level 2 adds the use of HTTP response codes and HATEOAS. Level 3 adds additional hypermedia controls to further enable discoverability and self-description of the API.

CRUD functions

HTTP Verb CRUD
POST Create
GET Read
PUT Update/Replace
PATCH Update/Modify
DELETE Delete

Roy Fielding, co-found of HTTP-server project recognized that the web’s scalability was goverened by a set of key constraints.

Client-Server: Separation of concerns is a core theme of client-server constraints.

Uniform-Interface:Interaction between the web’s components-meaning its clients, servers, and network-based intermediaries- depened on the uniformity of their interfaces.

What should be uniform then?

  • identification of resources : should have a unique identifier
  • Manipulation of resources through representation: representation itself is the way to interact with the resource. through JSON, HTML
  • self descriptive messages: to update something, you need its id and what to update. whatever is required, it should be present
  • HATEOAS: (Hypermedia as the engine of application state) Hypermedia are links and navigational element allowing client to discover and interact with the realted resource. HATEOAS is a key concept that allows for dynamic, self-describing APIs that can evolve over time without breaking clients.

Layered System:Other things between client and servers, such as reverse proxies with nginx, cdns etc

Cache: storing contents somewhere so instead of server sending data, it is the caching server that sends the data.

Stateless :no state of client should be memorized by server.

Code on demand: remote functions(firebase functions) ….

Identifier Design With URL

RFC 3986 defines the URI Syntax as

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
  • Forward slash separator (/) must be used to indicate a hierarchical relationship api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares

  • Trailing forward slash(/) shouldn’t be included in urls. Because it adds no semantic value and may cause confusion.

    api.canvas.net/shapes/ 👎

    api.canvas.net/shapes 👍

  • Hyphen should be used to improve the readability of URIs api.canvas.net/blog/ashish-thapa/entry/my-post-is-awesome

  • Don’t use underscore(_) in urls. because visual cue for hypermedia is underline. bad_underscore_might_obstruct_to_think_url_might_have_spaces.

  • use lowercase letters for URI paths.

  • File extension shouldn’t be included in URLS, instead use content-type header.

URI path is for resource modelling. Example of well modelled path

api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares

Resource Archetypes

Resource Archetypes are the design patterns for handling resource modelling. Archetype is the original pattern or model of which all other things are representation or copies.

Document: basis of database record . For example: Document for Country collection are: Nepal, Czetch Republic, Germany etc. Documents are generally fixed and don’t change, unlike stores

Collection : basis of directory of resources. For example: User can be collection, Country can be collection, Songs can be collection.

Store: Model that manages a client resource repository. /user/{user_id}/blogs gets the blog of the user_id.

Controller: when HTTP verbs like PUT, GET, POST can’t say what action or resource will do, you use controller,

GET /user/{user}/songs/{playlist_id}


this looks like fetching playlist songs

GET /user/{user}/songs/{playlist_id}/play looks like user is trying to play a song

Here play is the controller


  • For document naming , use singular nouns. /leagues/**seattle**
  • for collection naming, use plural nous. /**leagues**/seattle
  • use verb phrase for controller names. such as play, register, gather etc
  • CRUD Function name should not be used in URIs such as GET /deleteUser?id=123 because you already have http verbs for that. better would be DELETE /user

URI Query Design

Query Part is always the transparent part of the API.

Cache must not vary their behaviour based on the presence or absence of query in the given URL.

  • Query part of url can be used to filter collection or stores
  • For Pagination use URL query

Interaction Design with HTTP

GET: must be used to retreive a represenation of a resource.

HEAD: must be used to retieve response headers. send the same response as GET but only headers.

curl --head api.something.com/greeting

PUT: for inserting and updating a stored resource

POST: is semantically open-ended. it allows a method to take any action, regadless of its repeatability or side effects. that is why post method is considered unsafe . Because it can do anything. might end up doing same thing twice on resubmission.

DELETE : to delete a record*.*

Response status Code

201: resource was successfully created

202: async action was started

204: for when response body is empty

301: moved permanently

400: bad request for non specific failure

401: unauthorized

403: forbidden

404: not found

Metadata design

Content-type : should be all http response, which suggests the type of data found in message body

content-length: it is required. Length of the content

last-modified: it is required. timestamp that happened to alter the representational state of resource

eTag: for caches to be more efficient and save bandwidth, as a webserver doesn’t need to resend a full response if the content was not changed.

if-match : this makes the request conditional. If resource matches one of the ETag Values then only it will return the requested resources.

cache-control: reduce client perceived latency, to increase reliabilty, and to reduce load on API servers. it takes max-age value.

cache-control: max-age=60, must-revalidate

cache-control: no-cache , if no caching is required. and then expires: 0

Media type

type "/" subtype *( ";" parameter )

type might be application, audio, image, message, model, multipart, text or video

There are vendor specific media types application/vnd.ms-excel