Categories
Uncategorized

Popular explain RESTful

1 What is RESTful

Baidu, RESTful, many of which are found in the data speak clear, after reading do not know what to say is, leading to a lot of people do not quite understand RESTful. Look at the common explanation:

(1) describe the same God REST is not a “rest” means, but Representational State Transfer short, that the performance of the state transition layer.

“Presentation layer state transfer” What the hell?

(2) Description foggy

    REST refers to a set of architectural constraints and principles, if a framework and principles consistent with the constraints of REST, it is called RESTful architecture.

    RESTful architectural style is a kind of software, rather than the standard.

I can read a little, but still foggy.

Summary (3) Great God’s word incisive look great God know almost Ivony summary:

URL locate resources by using HTTP verbs (GET, POST, DELETE, PUT) operation is described.

RESTful web service is a design style, style means that we default but not mandatory.

2 RESTful Detailed

2.1 with a URL to locate resources

REST is the main resource, the so-called “resource” is a specific information on the network, for example: a picture, a text, a service. In short, it is a thing actually exists, and is used to point to this URL resource.

E.g:

https://api.example.com/users

The URL to see that this is an operation of user resources. URL term to use only the specified resource does not include the operation. why?

To include the operation, and that there are at least four kinds of CRUD, then a interface to become embodiment, at least four:

https://api.example.com/add_user
https://api.example.com/delete_user
https://api.example.com/update_use
https://api.example.com/get_user

Too much, simple enough.

2.2 describes operation using HTTP verbs

It describes how to operate it? The answer is to use HTTP verbs.

HTTP verbs, many people may At first glance a little Mongolian, I do not know what, in fact, is to use our web page request GET, POST and other operations. We usually use the most is the GET and POST (for example, when writing crawlers are basically two), commonly used as well as PUT, PATCH, DELETE.

Operation of resources, nothing less CRUD (CRUD), a RESTful, each corresponding to a HTTP verbs CRUD operations.

    GET: Retrieve the corresponding operation (query)

    POST: Create operation corresponding to

    DELETE: Delete operation corresponding to

    PUT: Update operation corresponding to

    PATCH: Update operation corresponding to

The difference between 2.3 POST and PUT

Speaking generally, when the corresponding HTTP verbs to CRUD, PUT are corresponding to the Update operation. But in fact, PUT can do Create operation. Two differences:

    URL: POST does not need to be assigned to an individual, such as the new user interface POST / api / users. PUT need to specify a URL to a specific individual, such as PUT / api / users / 1, 1 if the user exists, Update, or Create. This is well understood, POST is determined to add, insert the time is not required where conditions; PUT versa, update of time without where, worked as a junior partner, please raise their hands. In addition, PUT, when not every user will build an interface, here is the need to use the route, usually written PUT / api / users / {id}, so that you have a general. Here the route not start speaking up.

    Idempotent: PUT is idempotent, while POST is non-idempotent. About idempotency, see below.

The difference between 2.4 PATCH and PUT

PATCH after 2010 to become the official http method, which is a supplement to the PUT. In the absence of the PATCH, update operations are performed with PUT, this time we usually have a logical interface rules, such as: If a property of an object is null, then no update of the attributes (fields) value, by which ways to avoid the operation of full coverage. PATCH now have solved this judgment, in the PUT operation regardless of the property is not null, are updated on an update to a non-null in the PATCH interface. Further, PATCH non-idempotent.

2.5 alternative POST

According to REST suggested query to use the GET method, but the reality of dealing with them more trouble, such as: report statistics query parameters need to pass a lot, if the GET method, then the interface receives many parameters, the interface is difficult to see, usually java object to be packaged, but not support GET method object by reference, so it is boring;

In this case, the easiest way is to change the POST method, and many companies are so dry. REST visible only suggested, not mandatory constraints.

Added: Idempotence

Idempotent (Idempotence) could have been on a mathematical concept, defined not say, looked dizzy.

And later extended to the field of computer, described as:

Operating a process or service, any influence which are generated repeatedly with the same execution time impact.

Idempotent a method using the same parameters, it makes several calls and call time, impact to the system is the same. Therefore, the method idempotent, do not worry repeat the system will cause any change.

For example, mobile phone prepaid balance user X is 2 million, he Alipay to the mobile phone charge 100 yuan bill, if this operation is described as “give account balance X increased by 100 yuan,” it is non-idempotent operation is repeated several operators a big loss. However, if this operation is described as “X of the account balance to 102 yuan”, then this operation is idempotent. simply put:

    Idempotent operations: the balance of the account of X = 102 yuan;

    Non-idempotent operations: the balance of the account is increased X 100.

Note: Examples of idempotent here is not rigorous, this paper is not about idempotency, so just give a simple example, not depth.

Other details of 3 RESTful

3.1 naming convention

    (1) all lowercase, or a _ – cable.

For example I have given the example above:

https://api.example.com/add_user

The reason why no hump nomenclature, because early URI usually indicates that the file path on the server, and the server is different for different case sensitivity for compatibility with the provisions of different servers so it can not be mixed uppercase and lowercase letters.

    (2) URL only specify the resource with the term, because the core REST is a resource, and represents the natural resources of the word is a noun.

    (3) resource represented as a complex.

Version 3.2

One way is to add a version number in the URL, for example:

https://api.example.com/v1/users

Another method is to add the version number in the Accept header field of the HTTP request, for example:

Accept: version=1.0

Although there are many blog says in the recommended version is recommended to add information in the header, because resources represent different versions it remains the same, so it should not be a different URL. But to understand my current situation point of view, the vast majority of companies are the version number in the URL, and highly recommended, simple and intuitive.

Add in the URL of the version number of examples can be found online, as shown in the examples are written on me. But Jack_Zeng noted that such ambiguity is easy to write, will be mistaken for v1 is part of the resources are generally write:

https://api.example.com/users?api-version=1

3.3 HTTP status code

Know almost another interpretation of the great God RESTful compared to Ivony more than a word, he used three words to describe:

    What I want to know watch Url

    See http method to know what

    See http status code will know the outcome

The first two sentences and Ivony is a meaning. I think this third sentence summary was also very classic.

More than 100 http status code, we do not need to use all, just need to know which are commonly used on it

    200 – OK – everything is normal

    201 – OK – a new resource has been created

    204 – OK – Resources deleted successfully

    304– no change, clients can use the cached data

    400 – Bad Request – call illegal, should describe the exact error in the error payload

    401– not certified, authenticated users need to call

    403– not allowed, the server parses and normal request, but the call is rejected or not allowed

    404 – not found, the specified resource does not exist

    422– body can not be specified in the request – only entities can not handle the server, such as an image can not be formatted, or significant loss field

    500 – Internal Server Error – standard server errors, developers should try to avoid this error

References:

  • https://www.zhihu.com/question/28557115
  • https://blog.csdn.net/mingjia1987/article/details/79651241

Leave a Reply