REST Richardson Maturity Model

Richardson Service maturity model describes the normative model and development path of REST services, he REST application is divided into four levels:

level0

As only the transmission channel http

level1

Resources for the center

level2

Use http Action Semantics

level3

Control the use of hypermedia

The four-level description of the steps and process specifications of REST service implementation. Although the entire model is divided into four levels, but generally in practice, to achieve the third layer, fourth layer portion reaches substantially the entire api structure allows to maintain a clear and consistent. In addition to the general portion of the inlet api change, resource links along with most other entry corresponding to the api change, level3 achieve some can be.

Talk about these four levels of understanding:

level0

level0 requirement to use http as the transport mode, which unified the selected transmission mode, but also the follow-up to a higher level foundation.

level0 does not specify how to use http, so when level0 service scheduling style can be a variety of ways, representation may be varied, such as:

RPC-style url

rpc url to create a style can be as follows
```
 http://example.com/createUser?name=foo
 http://example.com/getOrder?id=bar
```
This way leads to link diverse resources, links can only be used once, the caller always need to find the corresponding documents
Without limiting the movement and status http

No task http restrictions on movement, there is no clear status of the resource limit
```
 GET http://example.com/createUser?name=foo  404
 GET http://example.com/getOrder?id=bar      200
```
Handling of resources and action http semantic conflict, it has been only the GET method does not fully leverage the semantics of http.

Status code indicates that people will be ambiguous, 404 represents the original user does not exist, or failure to create?

level0 is a very low level of maturity, can not bring good experience to the user in level0. Http user to know the way to make the call, but the call each interface, you need to see a corresponding interface documentation, url style and interface parameters, return values style inconsistent.

level1

level1 had a lot of changes: a resource-centric!

To act as the center of resources is hope providers and users interfaces are for entrance to provide solutions around the management of resources. Provider in the design of the interface, first consider what resources are exposed to outside; when users use, first consider what you want to access the resource.

Resource-Center is also reflected in the design url:

/users/
/users/?name=foo
/users/1
/orders/
/orders/1

Each exposed interface, a resource indicated by the first structure, such as a set of users, a single user. (For collection Here controversial, some people think it should be in the singular way to indicate the type, some people think that the use of the plural represents a collection of individuals prefer to use a set of representation).

On the basis of resources, you can add the appropriate query filter conditions, and so on down the page references.

It returns the result of the operation of the resources is represented by the general resources, but also to some extent the results of encapsulation, expressed more semantic.

level2

http protocol is to give resource-centric model provides a good framework, http action, queries, hyperlinks, can be a good response code is mapped to a resource-centric model to go.

Make full use of the http protocol, you can reduce a lot of inconsistent design.

http action map provided resources to operate:

GET     获取资源，无副作用，具备幂等性
POST    创建资源，有副作用，不具备幂等性
PUT     创建或更新资源，有副作用，具备幂等性
PATCH   部分更新，有副作用，具备幂等性
DELETE  删除资源，有副作用，具备幂等性

But the operation will change the resources of the state, this is a side effect. When the results remain the same, this is called idempotent, idempotency distributed environment for the realization of a lot of sense.

These two concepts can help decide what action to use a kind of http verbs exposed.

Note that the part of the client does not support a complete list of actions, we need to use some alternative ways to support, such as a hidden method way of spring, in the form with a hidden _methodfield that action, coupled with server-side HiddenHttpMethodFilter jointly support:

<form method="POST" action="/users/1">
    <input type="hidden" name="_method" value="PUT">
</form>

Resources to weather as an example, the system provides weather forecasts api query, the query does not change the state of the weather, you can use the following way

GET /weather/

But this url can not meet the power requirements of each region, the weather is different every day, so the time together with regional and

GET /weather/cn/guangzhou/20191201

Such url idempotency can meet the requirements of each query will get the same results to a certain extent, it can also be cached in the browser or on the CDN.

On the response code, it should also be consistent with the semantics of http, common

200 成功
404 找不到资源
301/302 永久/临时转移

level3

With the front of several levels, based on REST entire structure is very clear, but there has not been a problem processing: position change of resources, references to external resources.

With the upgrade, a likely location of the resources will be transferred to other places, may be abandoned. To reference resources, it is necessary to use some method of linking representation, rather than just json or xml data.

In REST related book, will refer to HATEOAS (Hypertext As The Engine Of Application State) In this manner, it is coupled with a corresponding link resources, with links to navigate between the resources.

In this way, the Smart Client can be implemented to some extent, to be able to automatically locate the corresponding resource.

See example on a spring-hateoas

{
  "_links": {
    "self": {
      "href": "https://myhost/person/1"
    },
    "curies": {
      "name": "ex",
      "href": "https://example.com/rels/{rel}",
      "templated": true
    },
    "ex:orders": {
      "href": "https://myhost/person/1/orders"
    }
  },
  "firstname": "Dave",
  "lastname": "Matthews"
}

The entire exterior of the orders, the resources are not in the current service nodes, using the HAL way indicates a link to this resource, so that the client can find this resource successfully.

Level3 implementation will be relatively little complicated, as previously described, most of the api only need to json result, but if it comes to crossing system call, hateoas is an inescapable pit.

Not a silver bullet

This four progressive levels of maturity will help guide our thinking REST api design, but the reality of the system needs are diverse, and none can be applied everywhere invincible solutions.

For extreme performance requirements of the system, may not be suitable for use in combination http + rest json, you may want to use a more compact rpc + protobuff programs; integration with legacy systems also need to consider some technical architecture, no brain do not choose REST. Reality system requires us to always trade-offs in various scenarios.