idempotence

Definition 1.

Idempotence is a promise (rather than an implementation) of a system service. It promises that multiple external calls will have the same effect on the system as long as the calling interface succeeds. Services declared idempotent assume that external invocation failures are the norm, and retries are inevitable after failures.

Idempotent is not just one (or more) request that has no side effects on the resource (such as a query database operation that has no impact on the database). Idempotent also means that the first request has side effects on the resource, but subsequent requests do not have side effects on the resource. Simply put, the result of accessing the REST service multiple times does not change.

Case 2.

Taking SQL as an example, there are three scenarios, and only the third scenario requires developers to use other policies to ensure idempotency:

1,SELECT col1 FROM tab1 WHERE col2 = 2; No matter how many times you do it, it doesn't change the state. It's naturally idempotent.2And the UPDATE tab1SET col1 = 1 WHERE col2 = 2; The state is the same no matter how many times it succeeds and is therefore an idempotent operation.3And the UPDATE tab1SET col1 = col1 + 1 WHERE col2 = 2; The result of each execution changes, which is not idempotent.Copy the code

3. Idempotency in HTTP

The HTTP protocol specifies that PUT, GET, and DELETE requests are idempotent, while POST is non-idempotent. When an interface is defined to be accessible by POST requests, its impact on the database is non-idempotent. So when you insert new data, you use POST. When updating data, use the PUT method. When querying data, use the GET method. When deleting data, use the DELETE method.

4. Idempotence and security

  • Security: does not change the state of the resource and can be understood as read-only;

  • Idempotent: Execution once and execution N times have the same effect on resource state changes.

RESTful interface design standards

Definition 1.

Representational State Transfer (REST) represents State transition. REST is a set of architectural constraints and principles. If an architecture conforms to REST constraints and principles, we call it a RESTful architecture. REST itself does not create new technologies, components, or services, but the idea behind RESTful is to use the existing features and capabilities of the Web to better use some of the principles and constraints of existing Web standards. Although REST itself is heavily influenced by Web technologies, the REST architectural style is not theoretically tied to HTTP, but currently HTTP is the only instance of REST.

2. Select a protocol method

In Spring4.3, @getmapping, @postmapping, @putmapping, @deletemapping and @patchmapping are introduced to help simplify the mapping of commonly used HTTP methods and better express the semantics of annotated methods.

@GetMapping

@requestMapping (value = “/get/{id}”, method = requestmethod.get)

Function: corresponding query, obtain data, indicating that it is a query request.

@PostMapping

@requestMapping (value = “/add/user”, method = requestmethod.post)

Effect: corresponding to add, add data, indicating an add request.

@PutMapping

@requestMapping (value = “/modify/user”, method = requestmethod.put)

Action: Corresponding to update, update data, indicating an update request.

@DeleteMapping

@requestMapping (value = “/delete/{id}”, method = requestmethod.delete)

Action: Delete, delete data, indicating a deletion request.

@PatchMapping

PatchMapping is a supplement to PUT. PUT focuses on the update of the whole, while PATCH is the update of the local.

3. The URI design

URI

Uris represent resources, which typically correspond to entity classes in the server-side domain model.

URL design specification

  • All lowercase letters.
  • Use a hyphen “-” instead of an underscore “_”.
  • The noun denotes a collection of resources. Use the plural form.
  • Avoid urIs that are too deep. If the URIs are too deep, they may swell and become difficult to maintain.

A single resource and a collection of resources

  1. A single resource

    / upshot/upshot/upshot/upshot/upshot 2; 3 // Zoo with ids 1, 2, and 3Copy the code

  2. Resource collection

    /zoos/ zoos/ all animals // all animals in the zoo with ID 1Copy the code

case

  1. The GET: query

    GET /zoos: lists all zoos GET /zoos/ID: obtains information about a specified zoo GET /zoos/ID/animals: lists all the animals in a specified zooCopy the code

  2. POST: Creates a single resource. POST is generally initiated to a RESOURCE set URI

    POST/upshot: A new zooCopy the code

  3. PUT: Fully updates a single resource. The client provides a complete updated resource

    PUT /zoos/ID: Update information for a specified zoo (provides full information about that zoo)Copy the code

  4. PATCH: Partially updates a single resource. The client provides the fields to be updated

    PATCH /zoos/ID: Update information for a specified zoo (provides partial information for that zoo)Copy the code

  5. DELETE: DELETE

    DELETE /zoos/ID: deletes a zoo DELETE /zoos/ID/animals/ID: deletes a specified animal from a specified zooCopy the code

4. Response data design

  • GET /collection: Returns a list (array) of resource objects
  • GET/Collection /resource: Returns a single resource object
  • POST/Collection: Returns the newly generated resource object
  • PUT/Collection/Resource: Returns the complete resource object
  • PATCH/Collection/Resource: Returns the complete resource object
  • DELETE /collection/resource: Returns an empty document

5. A status code

  • 200 OK – [GET] : the server successfully returns the requested data, which is Idempotent.
  • 201 CREATED – [POST/PUT/PATCH] : Data is CREATED or modified successfully.
  • 202 Accepted – [*] : indicates that a request has been queued in the background.
  • 204 NO CONTENT – [DELETE] : The user succeeded in deleting data.
  • 400 INVALID REQUEST – [POST/PUT/PATCH] : An error occurs in the REQUEST sent by the user. The server does not create or modify data. The operation is idempotency.
  • 401 Unauthorized – [*] : Indicates that the user does not have permission (the token, user name, or password is incorrect).
  • 403 Forbidden – [*] Indicates that the user is authorized (as opposed to the 401 error), but access is Forbidden.
  • 404 NOT FOUND – [*] : The user requested a record that did NOT exist, the server did NOT perform the operation, the operation is idempotent.
  • 406 Not Acceptable – [GET] : The format requested by the user is Not available (for example, the user requested JSON format, but only XML format).
  • 410 Gone -[GET] : The requested resource is permanently deleted and cannot be retrieved.
  • 422 Unprocesable Entity – [POST/PUT/PATCH] An authentication error occurred while creating an object.
  • 500 INTERNAL SERVER ERROR – [*] : An ERROR occurs on the SERVER, and users cannot determine whether the request is successful.