Getting Start on REST​

getting_start_on_rest.md

Getting Start on REST

A Simple Definition

REST is a style and a set of guide lines for web service, such as web API.

It

• is resource oriented
• uses HTTP method to convey method information
• uses URL to scope the resource to operate on

An Example

Suppose a set of REST web api for CRUD operations on web posts:

• POST /posts

  Create a new post

• GET /posts

  Get posts, optionally with some query parameters like category and tag, etc.

• GET /posts/:id

  Get a single post by id

• PUT /posts/:id

  Update a post

• DELETE /posts/:id

  Delete a post

Here the resource is post/posts. The HTTP methods POST/GET/PUT/DELETE stand for operations on the resource. And the URLs, such as /posts and /posts/:id, are used to scope the resource to operate on.

Constraints on HTTP

REST enforces constraints on how HTTP is used.

• Method

  Besides the semantic meaning aforementioned, GET/DELETE/PUT methods require idempotent operations, while POST/PATCH not.  

• Status code

  It indicates the operation result. Which codes are returned depends on the HTTP method and the operation result.

• Entity body and media type

  The request/response should have proper Content-Type for its entity body. That means not only the information format, such as application/json, but more importantly, the semantics, like application/vnd.collection+json.

Principles Behind the Scenes

How REST makes use of HTTP is determined by the principles of REST. Some important ones are:

• Client-server architecture

  It separate UI concerns from data storage concerns so that both parts can evolve independently.

• Statelessness

  No client's context information is held on server between requests. Each request contains all necessary information to service the request.

• Cacheability(HTTP cache)

  Response should denote if it's cachable or not, and request can be serviced from cache by intermediaries.

• HATEOAS(Hypermedia As The Engine Of Application State)

  A REST client should be able to dynamically discover available operations and resources that are provided by a REST server.

Best Reads

• RESTful Web Services by Sam Ruby, Leonard Richardson
• RESTful Web APIs by Leonard Richardson, Sam Ruby, Mike Amundsen
• RESTful Web Services Cookbook by Subbu Allamaraju