REST API

Uniform interface

The REST uniform interface embraces all aspects of the HyperText Transfer Protocol, version 1.1 (HTTP/1.1) including its request methods, response codes, and message headers.​

The REST uniform interface is based on three fundamental elements:

  1. Resources – How can we express where the data is being transferred to or from?

  2. HTTP Methods – What are the protocol mechanisms used to transfer the data?

  3. Media Types – What type of data is being transferred?

API

Rule: API scope [api-scope]

An API bundles a set of resources which are functionally related and form an autonomous unit of business logic.

Compare an API to the concept of Services in service-orientation or the concept of Bounded Contexts in Domain-Driven Development.

Rule: API format [uri-format]

The URLs of a REST API SHOULD have the following structure:

https://host/pathPrefix/apiName/vmajorVersion/resources

example: https://api.example.org/demo/v1/REST/employerProfile/v1/profiles

https://

Services are at least secured on transport level using a one-way TLS connection. The implicit port is 443.

host

Hostname is determined by the environment where the API is deployed

pathPrefix

Optional path prefix to discriminate between REST APIs and other resources on the same host. (example: /REST)

apiName

Name of the API that groups a functional consistent set of resources. The API name consists of one or multiple path segments and SHOULD be written in lowerCamelCase (example: /referenceData/geography).

majorVersion

Major version numbers are integers and start at 1. See API versioning.

resources

All path segments identifying the actual resources.

Richardson Maturity Model

The Richardson Maturity Model (developed by Leonard Richardson) breaks down the principal elements of a RESTful interface into three steps. In order to be compliant to the uniform interface as described by Roy Fielding, all three levels must be fulfilled.

  1. Resources — Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources, each represented by a unique URI.

  2. HTTP Methods — Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.

  3. Links — Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.

Rule: Maturity level [api-matur]

All REST services MUST at least respect level 2 and desirably achieve level 3.

References