HTTP REST APIs

使用以下提供的信息以帮助确定何种Method,以应用不同场景：

1.HTTP GET

GET 请求获取资源信息 - 且不要以任何方式修改资源，因为 GET 请求不提倡修改资源状态，由此也被称为safe methods。
此外，GET APIs 应该是等幂的。即除非其他的 API （POST or PUT) 修改了服务器资源状态，任何时候发送多次完全相同的 GET 请求应当返回完全相同的数据。

1.1 GET API 响应码#Response Codes

万一在服务器上没有找到资源，则API 必须返回 HTTP response code 404 (NOT FOUND)

1.2 示例URIs

HTTP GET http://www.feishuai.vip/users
HTTP GET http://www.feishuai.vip/users?size=20&page=5
HTTP GET http://www.feishuai.vip/users/123
HTTP GET http://www.feishuai.vip/users/123/address

2. HTTP POST

POST APIs 用以创建新的子级资源，例如：某个目录下的子文件，又或者某个数据库表的新增行。
当谈及 REST。 POST 方法是用于给某个集合资源对象创建一个新的资源
除非响应包含了适当的或者头字段，该METHOD 的想用是不能够被缓存的。
请注意，POST 请求，既不安全，也不幂等。并且调用两次完全相同的 POST 请求将会导致产生包含除了id,其他完全相同信息的两个不同的资源。

2.1 POST API Response Codes

Location 头。

2.2 示例 URIs

HTTP POST http://www.feishuai.vip/users
HTTP POST http://www.feishuai.vip/users/123/accounts

3. HTTP PUT

PUT APIs 主要是用于更新一个既存的资源(如果这个资源不存在，则该API也可以选择要不要创建一个新的资源）。
如果这个请求通过了一个缓存，并且 request-uri 标识了一个或多个当前缓存的实体，那么这些条目应当被视作过时的。 PUT 方法的响应式不可缓存的。

3.1 PUT API Response Codes

如果一个存在的资源被修改了，那么服务器应该返回 200 (OK) 或者 204 (No Content) 响应状态码，以告知请求成功完成。

示例 URIs

HTTP PUT http://www/feishuai.vip/users/123
HTTP PUT http://www/feishuai.vip/users/123/accounts/456

[POST 和 PUT APIs 的区别(https://restfulapi.net/rest-put-vs-post/) 能够从请求 URIs 观察一二： POST 请求是针对资源集合
对象发出的，而 PUT 请求则是针对单个资源。

4. HTTP DELETE

删除资源(由请求 URI 标识)。
DELETE 操作是等幂的，如果你DELETE一个资源，那么它会从资源集合中移除掉目标
有些人可能认为这使得DELETE方法是非幂等的。这是讨论和个人意见的问题。
如果这个请求通过了一个缓存，并且 request-uri 标识了一个或多个当前缓存的实体，那么这些条目应当被视作过时的。 DELETE 方法的响应式不可缓存的

4.1 DELETE API Response Codes

如果该操作处于等待队列中，那么应该返回 202 (Accepted) 。
对同个资源重复操作 DELETE API将不会改变输出 —— 然而，当对一个资源执行第二次操作的时候一般会返回 404（NOT FOUND) 应为它已经被删除掉了。

4.2 示例 URIs

HTTP DELETE http://www.feishuai.vip/users/123
HTTP DELETE http://www.feishuai.vip/users/123/accouts/456

5. HTTP PATCH

HTTP PATCH 请求被用于对一个资源进行部分更新 #to make a partial update
如果你看到一个PUT 请求也在修改一个资源实体，那么让它更加精确 —— PATCH METHOD 就是正确的选择专用于部分更新一个既存资源。并且。你应该仅在需要替换某个资源的时候使用 PUT 请求。

浏览器，服务器，以及web应用框架对PATCH 的支持并不是统一的， IE8，PHP， Tomcat. Django 等等都对 PATCH 不支持或者缺乏支持。

HTTP GET /user/1

产生如下响应：

{ "id": 1, "username": "admin", "email": "email@example.org" }

一个简单的PATCH 请求以更新email将会像下面这样：

HTTP PATCH /users/1
[{ "op": "replace", "path":"/email", "value": "new.email@example.org" }]

根据以下 HTTP 规范，可能会有以下操作：

[
{ "op": "test", "path": "/a/b/c", "value": "foo" },
{ "op": "remove", "path": "/a/b/c" },
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar"] },
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/c" },
{ "op": "copy", "from": "/a/b/c", "path": "/a/b/c" },
]

PATCH Method 请不是 POST 或者 PUT Methods 的替代品，它不同于替换整个资源

6. HTTP Methods 总结

The below table summarises the use of HTTP methods discussed above.

HTTP Method	CRUD	Collection Resource (e.g. /users)	Single Resouce (e.g. /users/123)
POST	Create	201 (Created), ‘Location’ header with link to /users/{id} containing new ID	Avoid using POST on a single resource
GET	Read	200 (OK), list of users. Use pagination, sorting, and filtering to navigate big lists	200 (OK), single user. 404 (Not Found), if ID not found or invalid
PUT	Update/Replace	405 (Method not allowed), unless you want to update every resource in the entire collection of resource	200 (OK) or 204 (No Content). Use 404 (Not Found), if ID is not found or invalid
PATCH	Partial Update/Modify	405 (Method not allowed), unless you want to modify the collection itself	200 (OK) or 204 (No Content). Use 404 (Not Found), if ID is not found or invalid
DELETE	Delete	405 (Method not allowed), unless you want to delete the whole collection — use with caution	200 (OK). 404 (Not Found), if ID not found or invalid

7.相关术语#Glossary

7.1 Safe Methods

GET, HEAD, OPTIONS, TRACE methods 被认为是安全 methods, 就像每个 HTTP 定义的， GET 和 HEAD methods 应该仅被用于资源的获取，且不会更新/删除服务器上的资源。

安全methods 允许用户代理#agents 其他methods,例如 POST, PUT, DELETE. 以这种独特的方式，使用户意识到可能正在要求采取不安全操作的事实 - 他们可以在服务器上更新/删除资源，因此应仔细使用。

7.2 Idempotent Methods #幂等方法

在HTTP 中， PUT, DELETE 以及上述的safy methods (GET, HEAD, OPTIONS, TRACE) 都是幂等操作。

resuful api

编程笔记 » HTTP REST APIs