REST API standards — REST Web Services

7 min readJun 25, 2018

I would say this article is a summary of REST API Design Rulebook By Mark Masse

What is REST

REST stands for REpresentational State Transfer.
REST was first introduced by Roy Fielding in the year 2000.
(He is known for REST and Apache, contributes URI, HTTP, and HTML)
REST uses HTTP protocol for data communication.
REST uses Text, JSON and XML to communicate with client and server.

But best restful design even don’t need superfluous documentation, because of HATEOAS, we will get to HATEOAS at the end.

RESTful Web Services are basically REST Architecture based Web Services.
REST + Web Services = RESTFul Web Services

Here are some of questions pop-up into my head when I develop RESTfull APIs. I’ll try to give solution most of these within this article

When should URI path segments be named with plural nouns?
Which request method should be used to update resource state?
How do I map non-CRUD operations to my URIs?
What is the appropriate HTTP response status code for a given scenario?
How can I manage the versions of a resource’s state representation?
How should I structure a hyperlink in JSON?

Resource Archetypes

API is composed of four distinct resource archetypes:

Document
Collection
Store
Controller

Document

Each URI below identifies a document resource:

Use “singular” name to denote document resource archetype.

api.cricket.restapi.org/leagues/ipl
api.cricket.restapi.org/leagues/seattle/teams/mumbai-indians
api.cricket.restapi.org/leagues/ipl/teams/mumbai-indians/players/lasith-malinga

Collection

Each URI below identifies a collection resource:

Use plural name to denote store resource archetype.

api.cricket.restapi.org/leagues
api.cricket.restapi.org/leagues/seattle/teams
api.cricket.restapi.org/leagues/seattle/teams/trebuchet/players

Store

A store never generates new URIs. Instead, each stored resource has a URI that was chosen by a client when it was initially put into the store.

Use plural name to denote store resource archetype.

http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists

Example
What will be the api URI & Method for below scenario?
There are resources for a music collage. and you need to assign existing student for teacher(mentor) as mentee.
Student:
Amendra(userId: 38, slug: amendra)
Teacher:
Victor Rathnayaka(userId: 75, slug: victor-rathnayaka)
Assume you are authenticated and authorized for execute this.
Answer
PUT api/teachers/75/mentees/students/38
PUT api/teachers/75/mentees/students/amendra
PUT api/teachers/victor-rathnayaka/mentees/students/38
PUT api/teachers/victor-rathnayaka/mentees/students/amendra

Controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Like a traditional web application’s use of HTML forms, a REST API relies on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods (create, retrieve, update, and delete, also known as CRUD)

Controller names typically appear as the last segment in a URI path, with no child
resources to follow them in the hierarchy. The example below shows a controller resource that allows a client to resend an alert to a user:

POST /alerts/245743/resend

URI Path Design

The following anti-patterns exemplify what not to do:

GET /deleteUser?id=1234 
GET /deleteUser/1234 
DELETE /deleteUser/1234 
POST /users/1234/delete

Rule: A singular noun should be used for document names

api.cricket.restapi.org/leagues/ipl/teams/mumbai-indians/players/lasith-malinga

Rule: A plural noun should be used for collection names

api.cricket.restapi.org/leagues/ipl/teams/mumbai-indians/players

Rule: A verb or verb phrase should be used for controller names

Like a computer program’s function, a URI identifying a controller resource should be named to indicate its action. For example:

http://api.college.restapi.org/students/morgan/register
http://api.ognom.restapi.org/dbs/reindex
http://api.build.restapi.org/qa/nightly/runTestSuite

Rule: CRUD function names should not be used in URIs

HTTP request methods should be used to indicate which CRUD function is performed.

DELETE /users/1234

CRUD is an acronym that stands for create, read, update, delete — the four standard, storage-oriented functions

URI Query Design

Rule 1: As a component of a URI, the query contributes to the unique identification of a resource. Consider the following example:

api.college.restapi.org/students/morgan/send-sms
api.college.restapi.org/students/morgan/send-sms?text=hello

The URI of a controller resource that sends an sms message.

The URI of a controller resource that sends an sms message with a text value of hello

Rule 2: The query component of a URI may be used to filter collections or stores

A URI’s query component is a natural fit for supplying search criteria to a collection or store. Let’s take a look at an example:

GET /users 
GET /users?role=admin

The response message’s state representation contains a listing of all the users in the collection. The response message’s state representation contains a filtered list of all the users in the collection with a “role” value of admin.

Rule 3: The query component of a URI should be used to paginate collection or store results

A REST API client should use the query component to paginate collection and store results with the pageSize and pageStartIndex parameters. The pageSize parameter specifies the maximum number of contained elements to return in the response. The pageStartIndex parameter specifies the zero-based index of the first element to return in the response. For example:

GET /users?pageSize=25&pageStartIndex=50

Identifier Design with URIs

Rule 1: Forward slash separator `/` must be used to indicate a hierarchical relationship

The forward slash / character is used in the path portion of the URI to indicate a hierarchical relationship between resources.

Example:

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

Rule 2: A trailing forward slash `(/)`should not be included in URIs

http://api.canvas.restapi.org/shapes/http://api.canvas.restapi.org/shapes

Adding /slash to end of the url not give any meaning, it’s only make confusion.
The basically REST API must generate and communicate clean URIs.

Rule 3: Hyphens (-) should be used to improve the readability of URIs

To make your URIs easy for people to scan and interpret, use the hyphen (-) character to improve the readability of names in long path segments. Anywhere you would use a space or hyphen in English, you should use a hyphen in a URI. For example:

api.example.restapi.org/blogs/mark-masse/entries/my-first-post

Rule 4: Underscores (_) should not be used in URIs

Text viewer applications (browsers, editors, etc.) often underline URIs to provide a visual cue that they are clickable. Depending on the application’s font, the underscore (_) character can either get partially obscured or completely hidden by this underlying.

To avoid this confusion, use hyphens (-) instead of underscores (as described in “Rule: Hyphens (-) should be used to improve the readability of URIs” on Rule 3).

Rule 5: Lowercase letters should be preferred in URI paths

When convenient, lowercase letters are preferred in URI paths since capital letters can sometimes cause problems. RFC 3986 defines URIs as case-sensitive except for the scheme and host components. For example:

http://api.example.restapi.org/my-folder/my-doc HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc

The above URI is fine. The URI format specification (RFC 3986) considers this URI to be identical to URI #1.

http://api.example.restapi.org/My-Folder/my-doc

This URI is not the same as URIs 1 and 2, which may cause unnecessary confusion.

Rule 6: File extensions should not be included in URIs

A REST API should not include artificial file extensions in URIs to indicate the format of a message’s entity body. Instead, they should rely on the media type, as communicated through the Content-Type header, to determine how to process the body’s content.

api.college.restapi.org/students/3248234/transcripts/2005/fall.json
api.college.restapi.org/students/3248234/transcripts/2005/fall

To enable simple links and easy debugging, a REST API may support media type selection via a query parameter as discussed in next Rule 6.1

Rule 6.1: Media type selection using a query parameter may be supported

To enable simple links and easy debugging, REST APIs may support media type selection via a query parameter named accept with a value format that mirrors that of the Accept HTTP request header.
For example:

GET /bookmarks/mikemassedotcom?accept=application/xml

Rule 7: Consistent subdomain names should be used for your APIs

The top-level domain and first subdomain names (e.g., soccer.restapi.org) of an API should identify its service owner. The full domain name of an API should add a subdomain named api.
For example:

http://api.soccer.restapi.org

Rule 8: Consistent subdomain names should be used for your client developer portal

Many REST APIs have an associated website, known as a developer portal, to help onboard new clients forums, and self-service provisioning of secure API access keys.

http://developer.soccer.restapi.org

Resource Modeling

The URI path conveys a REST API’s resource model, with each forward slash separated path segment corresponding to a unique resource within the model’s hierarchy.

http://api.cricket.restapi.org/leagues/ipl/teams/mumbai-indians

indicates that each of these URIs should also identify an addressable resource:

http://api.cricket.restapi.org/leagues/ipl/teams http://api.cricket.restapi.org/leagues/ipl http://api.cricket.restapi.org/leagues 
http://api.cricket.restapi.org

Resource modeling is an exercise that establishes your API’s key concepts. This process is similar to the data modeling for a relational database schema or the classical modeling of an object-oriented system.

Interaction Design with HTTP

Request Methods

HTTP response success code summary

HATEOAS

Hypermedia as the engine of application state (HATEOAS)

Hypermedia as the engine of application state (HATEOAS) A resource’s state representation includes links to related resources. Links are the threads that weave the Web together by allowing users to traverse information and applications in a meaningful and directed manner. The presence, or absence, of a link on a page is an important part of the resource’s current state.

https://api.github.com/users/cagline

This is not practical when we develop api’s that’s why famous api’s like facebook, google also not use HATEOAS much.
But github is embrace this HATEOAS feature very well,

I would say this article is a summary of REST API Design Rulebook By Mark Masse
I would recommend you to read this whole book if you wanted to be a professional of RESTfullweb services.