Table of Contents outline true
REST
| outline | true |
|---|
Introduction
REST is not a standard, but a Web application development architectural style, which can be understood as a design pattern. REST-based HTTP, URI, XML and widely popular these existing protocols and standards, along with REST, HTTP protocol to obtain a more correct use. SOAP and WSDL-based Web services, REST model provides a more concise compared to realization.
...
A typical URI in the table below, including the protocol name, host name, port services, and other resources to address and query string:
| Name | Description |
|---|---|
| specification | scheme://[host]:[port]/path?queryString |
| scheme | Protocol term , typically http or https |
| host | (DNS) Host Name or IP address |
| port | Port |
| path | Resource address, logical Hierarchy Use '/ 'delimited |
| ? | Resources used to separate address and query string of symbols |
| queryString | Query string, scope information ampersand method to separate the query conditions separated by commas orderly scope information separated by semicolons no information about the scope of the order |
Resource Address Description
...
Resource Path Information
| ServiceType | ServiceName | ServiceVersion | PathInfo |
|---|---|---|---|
| openoapi | catalog | v1 | /servicetemplates |
| openoapi | catalog | v1 | /servicetemplates/{serviceTemplateId} |
| oepnoui | log | v1 | /info/syslogs |
| oepnoui | log | v1 | /statisticinfo/syslogs |
Absolute URI and Relative URI
...
Cacheable ways to obtain a response to previous requests from the cache at a mid-tier caching.
| Method | Safe | Idempotent | Cachable | REST Use |
|---|---|---|---|---|
| GET | Yes | Yes | Yes | Query Resource |
| HEAD | Yes | Yes | Yes | |
| POST | No | No | No | Create Resource |
| PUT | No | Yes | No | Update Resource |
| DELETE | No | Yes | No | Delete Resource |
| OPTIONS | Yes | Yes | No | |
| PATCH | No | No | No | Update Resource |
| TRACE | Yes | Yes | No |
When a request for a resource does not support the corresponding request method, the server should return the status code 405 (Method Not Allowed); when the server does not know or does not support the corresponding request method, it shall return a status code 501 (Not Implemented).
HTTP server should implement at least the GET and HEAD methods, other methods are optional. In addition to the above-described method, a specific HTTP server can also extend custom method.
| Function | Resource Address |
| Add/Create | POST/books PUT/books/{id} |
| Delete | DELETE/books |
| Modify/Update | PUT /books |
| Query All | GET /books |
| Primary key query | GET /books/{id} GET /books?id=123 |
| Paging scope query | GET /books?start=0&size=10 GET /books/01,2012-02,2015 GET /books/hadoop;language=scala;type=xxx |
Resource Address Design Specification
...
- API Service
- Content service , static pages and js, css and other resources
| Function | scheme://[host]:[port]/path | queryString |
|---|---|---|
| API Service Specification | [[host\]]:[port]/openoapi/[Service Name]/v[Version Number]/[Resource]/ | queryparam1=xxx, queryparam2=xxx |
| Content Service Specification | [[host\]]:[port]/openoui/[Content of the resource]/index.html | None |
Note: The version number before lowercase letter 'v'
For example:
| Function | scheme://[host]:[port]/path | queryString |
|---|---|---|
| log API Service | [[host\:\[port\]/openoapi/log/v1/loginfo/syslogs]] | starttime=xxxx Endtime=xxxx |
| log Content Service | [[host\:\[port\]/openoui/log/]] | |
| alarm API Service | [[host\:\[port\]/openoapi/fm/v1/alarms]] | |
| alarm Content Service | [[host\:\[port\]/openoui/fm/]] |
Use path variables to express the resource hierarchy
...
JAX-RS2.0 defines the status code of the response javax.ws.rs.core.Response.Status and base exception class
javax.ws.rs.WebApplicationException, This exception contains the following sub-classes.
| Status Code | Request Type | Meaning | Exception class |
|---|---|---|---|
| 200 OK | [GET] | Server successfully returned the data requested by the user, the operation is idempotent | Response.Status.OK |
| 201 CREATED | [POST/PUT/PATCH]? | Create or modify user data successful | Response.Status.CREATED |
| 202 ACCEPTED | [*]? | Represents a request has been queued into the background (asynchronous task) | Response.Status.ACCEPTED |
| 204 NO CONTENT | [DELETE] | Delete user data successful | Response.Status.NO_CONTENT |
| 400 BAD REQUEST | [POST/PUT/PATCH]? | Request issued by a user error, the server does not operate create or modify data, the operation is idempotent | BadRequestException |
| 401 Unauthorized | [*] | Indicates that the user is not authenticated (token, username, password error) | NotAuthorizedException |
| 403 Forbidden | [*] | Indicates that the user is authenticated (401 errors are relatively), but access is prohibited. it used for unauthorized | ForbiddenException |
| 404 NOT FOUND | [*] | Request issued by the user is directed to a nonexistent record, the server does not operate, the operation is idempotent. | NotFoundException |
| 406 Not Acceptable | [GET] | Format requested by the user not available (such as a user request JSON format, but only XML format). | NotAcceptableException |
| 410 Gone | [GET] | Resource requested by the user is permanently deleted and can not be obtained | Response.Status.GONE |
| 422 Unprocesable entity | [POST/PUT/PATCH] | When you create an object, a validation error occurs. | |
| 500 INTERNAL SERVER ERROR | [*] | Server error occurs, the user will be unable to determine whether the request is sent successfully | InternalServerErrorException |