author githubId: golone

preface

Read two days RESTful summary of the notes, the first time in nuggets hair article, if there is fallacy also please big guys forgive.

concept

1. RPC oriented approach
2. SOA message Orientation
3. REST resource Oriented

REST:

Representational State Transfer (REST) is an Internet software architecture model developed by Roy Fielding in his doctoral thesis architectural Style and Web-based Software Architecture Design in 2000. REST became popular as soon as it was proposed. Quickly replacing the complex and bulky SOAP.

To understand REST, it’s best to understand Carefully Representational State Transfer, which literally translates as “representation State Transfer,” omits the subject and means “representation State Transfer of a resource.” The key words are “resource,” “representation layer,” and “State transformation.”

Resources:

A “resource” is an information entity on a network. REST specifies that a resource is uniquely identified by a URI (Uniform Resource Locator), through which any resource can be obtained.

The presentation layer:

“Resource” is just information, which can exist in a variety of ways (for example, a simple text can be expressed as TXT, HTML, XML, JSON, or even binary formats). We call the existence mode of the resource its “presentation layer”, which can be understood as the “view” of the resource. In REST, The URI only identifies the resource, not the presentation layer it is in. Its presentation layer is specified in the HTTP header by Accept and Content-Type, which are used to identify the “presentation layer” the resource is currently in.

State transformation:

“State” information including resource itself and its two aspects of the presentation layer (the concept may be I made, I don’t check the information in the “state” as a single concept, but I think we should add such a concept, or logically some blocked), “state” refers to the resources from a “state” change to another kind of “state”, This “change” may be a change in the presentation layer, or it may be a change in the information of the resource itself. The access interface notifies the server to perform a “state transition”, such as CURD:

REST specifies that HTTP method is used to inform the server of “state transition”. Specifically, different HTTP request methods are used to specify different operations, such as GET, POST, PUT, and DELETE, which correspond to CURD respectively. Inform the server to add, delete, change and check four state transformation.

These are the core concepts of REST, which, strictly speaking, have the following constraints:

1. Each resource has a unique resource identity.
2. Self-description of the message.
3. Self-description of resources.

RESTful:

If an architecture conforms to REST specifications, it is called a RESTful architecture, and Web services that use RESTful architecture are also called RESTful Web Services.

In a Restful Web Service, each URL represents a resource, so a URL cannot have a verb, only a noun, and even the noun used is usually corresponding to the name of a data table, which usually contains more than one record, so the noun in a URL is usually plural.

Supplement:

Here are a few of my references that I found interesting or professional:

1. An interesting article about RESTful apis: How to explain RESTful to your wife
2. Limitations of REST
3. If you want to know where REST comes from: Derive REST

Compared with REST, API design produced a more revolutionary theory GraphQL in 2015. The basic idea is to put an intermediate server between the front end and the back end, and then define a query language for the front-end to describe the required data, and the intermediate server receives the query sent by the front-end for parsing. Then automatically requests the corresponding interface and sorting data and then returned to the front, benefit is the front to get the data don’t have to request more than one interface, when a fix, routing, also need not remember interface parameters, no need to worry about these things front, just check it, it is similar to SQL, is very convenient, details you can see these two articles: REST will be obsolete, GraphQL will persist, REST 2.0 is here, it’s called GraphQL

URL design

RPC is verb-centric and RESTful is noun-centric.

When a new function is added, a new verb must be added, and the back end must realize the verb, and the front end must know the new verb and call it. Noun-centric is not so troublesome, no matter what new functionality is added, as long as no new resources are added, the URL is the same, the front and back end only need to focus on their implementation, do not need to be distracted on the interface. Note the following when designing RESTful interfaces based on nouns:

1. Single, plural, this is easy to understand, depending on the number of resources to determine which form of the noun, not to repeat.
2. Resources are classified into primary resources and sub-resources. Primary resources represent a class of resources, so primary resources should be placed in the middle of the URL instead of the end, for example, /users/friends. Users represent all users and friends represent all friends of the user.
3. Query: /v1/users? Id =x = /v1/users/:id = /v1/users/:id = /v1/users/:id
4. HTTP methods, RESTful does not allow verbs in urls. HTTP1.1 defines exactly eight methods to refer to eight verbs, so RESTful advocates using HTTP methods to describe common operations. For example, put, POST, GET, and delete correspond to resource curDs respectively.

Parameters:

Since URLS represent resources, can we take it one step further and make urls closer to SQL? This makes the interface more flexible. Based on this, RESTful apis have the following common parameters:

This can be done by adding the x-HTTP-method-Override field to the request header. This tells the server which Method to use, for example:

        POST /api/Person/4 HTTP/1.1
        X-HTTP-Method-Override: PUT

X-http-method-override then specifies that the request Method is PUT, not POST.

The response message

Status code:

To ensure that messages are self-descriptive, the following status codes should be used to represent common situations:

Do not return pure text:

The data returned by the interface should be in JSON format, and the content-type of the corresponding Response header should be set to Application/JSON. The front-end request should also explicitly tell the server to ACCEPT the JSON format, that is, the ACCEPT of the Request header should be set to Application/JSON. The JSON format is not RESTful. It is a popular data transfer format, similar to unwritten rules, which may change in the future. (2019-11-23

Provide links:

Users of apis do not necessarily know how urls are designed, so RESTful apis also require resources to be self-descriptive. One solution, as documented on Mr Ruan’s blog, is to link to the response data. This allows users to memorize one URL and discover other urls. This method is called HATEOAS. For example, GitHub’s API is documented at api.github.com. Visit it and you can get all urls, or visit one URL and return related urls. This way, users don’t need to remember the URL design, just look it up step by step from api.github.com.

Personal view

A RESTful API is a good way to implement a set of interfaces. It is very good to use it in multiple ways, but I don’t think it can be done completely according to its standards. For example, THE URL cannot contain verbs. Sometimes an API does more than CURD on a resource, which requires more verbs, so I think it’s normal to add a verb to the URL if necessary. (And I prefer to just use get and post, I don’t want to do too much fuss, adding a verb won’t kill you…

/users/123/articles/54 is a more appropriate way to use RESTful apis. So back-end when define routing can write to/users/articles / : userId / : articleId, first path, parameters, are centralized, more comfortable.