RESTful overview
RESTful is currently the most popular Internet software architecture. It has a clear structure, conforms to standards, is easy to understand, and is easy to expand, so it is being adopted by more and more websites.
REST is the abbreviation of Re presentational State Transfer, which was proposed by Roy Thomas Fielding in his doctoral dissertation in 2000 . The proposed design concepts and guidelines are:
1. Everything on the web can be abstracted as resources
2. Each resource should have a unique identifier, and operations on the resource will not change the identifier
3. All operations are stateless
4. Manipulate resources using standard methods (GET, POST, PUT, PATCH, DELETE)
RESTful use
| HTTP method | HATE | describe | idempotent | Safety |
| GET | /api/members | get member list | Yes | Yes |
| GET | /api/members/{id} | Get the specified member | Yes | Yes |
| POST | /api/members | Create a member | no | no |
| PUT | /api/members/{id} | Update all member information | Yes | no |
| PATCH | /api/members/{id} | Update member information | Yes | no |
| DELETE | /api/members/{id} | delete specified member | Yes | no |
| HTTP method | HATE | describe | idempotent | Safety |
| GET | /api/groups | get group list | Yes | Yes |
| GET | /api/groups/{id} | Get the specified group | Yes | Yes |
| POST | /api/groups | Create a group | no | no |
| PUT | /api/groups/{id} | Update all group information | Yes | no |
| PATCH | /api/groups/{id} | Update group information | Yes | no |
| DELETE | /api/groups/{id} | delete the specified group | Yes | no |
| GET | /api/groups/{id}/members | Get members of a specified group | Yes | Yes |
| GET | /api/groups/{id}/members/{memberId} | Get the specified members under the specified group | Yes | Yes |
Idempotency: Multiple accesses to the same RESTful interface result in the same resource state.
Security: Accessing the RESTful interface will not change the state of server-side resources.
Normative advice
1. The API uses the HTTPS protocol (https) through a secure channel as much as possible.
2. The request body and the response body are uniformly carried in json format, json uses Camel's naming rules, and the media type needs to be set to "application/json".
Example:
Request
Accept: application/json
Content-Type: application/json
Response
Content-Type: application/json
3. The request body and the response body are uniformly encoded in UTF-8, and the time is uniformly in UTC format: yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'.
4. URI template: /{domain}/{service or module}/api/{version}/{resource}, URI should be all lowercase letters, and phrase words should be separated by "-".
| name | illustrate | Example |
| domain | The name of the realm, if it is not necessary to distinguish the realm, it can be omitted | education finance (financial field) game (game field) |
| service or module | service or module name | account (account module) order (order service) storage (inventory service) |
| version | version number | v1 v2 v3 |
| resource | Services or In-Module Resources | users (user) products members |
5. For the operations of adding, deleting, modifying and checking resources, use the template: /{domain}/{service or module}/api/{version}/{resource}/action/{action}.
示例：/common/account/api/v1/users/action/login
Response message suggestion
1. If the resource list is obtained successfully , 200 is returned , and the response message body contains the total number of records, the current page number, the records on each page, and the corresponding resources.
Example:
Response Body
{
"total": xxx,
"pageIndex": xxx,
"pageSize":xxx,
"records":[
{ "id": xxx, "name":"xxx" },
{ "id": xxx, "name":"xxx" }
]
}
2. 获取指定资源成功返回200，响应消息体中包含该资源的信息。
3. 创建资源成功返回201，并在响应消息头中包含定位该资源的地址。
示例：
Response Headers
{
"pragma": "no-cache",
"server": "xxx",
"content-type": "application/json; charset=utf-8",
"location": "https://xxx/api/users/xxx", //资源访问地址
"content-length": "xxx"
}
4. 资源更新成功返回200，并在响应消息中体返回更新后的资源内容。
5. 资源删除成功返回204，响应消息体无内容。
6. 针对400 Bad Request客户端错误，可以在响应消息体中扩展状态码。
示例：
Response Code
401 Bad Request
Response Body
{
"code": 400001,
"message": "用户名或密码错误"
}
----------------------------------------------------------
Response Code
401 Bad Request
Response Body
{
"code": 400002,
"message": "邮箱已存在"
}
----------------------------------------------------------
Response Code
401 Bad Request
Response Body
{
"code": 400003,
"message": "邮箱地址错误"
}
7. 针对5XX的服务端错误，只在响应消息体中提供简单提示，不可打印错误日志信息。
示例：
Response Body
{
"message": "内部错误，请稍后再试或联系管理员"
}
7. 其他客户端错误的响应码，只在响应消息体中提供相应提示。
示例：
Response Code
401 Unauthorized
Response Body
{
"message": "用户未登录"
}
----------------------------------------------------------
Response Code
403 Forbidden
Response Body
{
"message": "权限不足"
}
----------------------------------------------------------
Response Code
404 Not Found
Response Body
{
"message": "请求资源不存在或已被删除"
}
常见响应码
| 响应码 | 说明 |
| 200 OK | 请求已成功 |
| 201 Created | 资源已创建 |
| 204 No Content | 请求已成功，但无返回内容 |
| 304 Not Modified | 缓存有效 |
| 400 Bad Request | 语义有误，当前请求无法被服务器理解，请求参数错误 |
| 401 Unauthorized | 当前请求需要用户认证（登录） |
| 403 Forbidden | 用户已认证（登录），但权限不足 |
| 404 Not Found | 请求源未在服务器上被发现 |
| 405 Method Not Allowed | 请求方法不能被用于请求相应的资源，如使用PUT方法访问只接受POST方法的API |
| 500 Internal Server Error | 服务端内部错误 |
| 502 Bad Gateway | 网关错误 |
| 504 Gateway Timeout | 网关超时 |