HTTP Methods 和 RESTful Service API 设计
2021-04-08 18:25
- 客户端调用：客户端把要创建的数据放在HTTP请求的Body中，比如Body数据是{title: "Are your lights on", author: "Donald C. Gause"}之后发送 HTTP POST 请求到
https://api.server.com/books - 服务端实现
- 服务端在收到客户端 POST 来的数据时，根据POST URL，发现应该创建books数据。
- 之后获取 body 里面的内容来创建一条新 book 记录并保存，如果一切正常，返回201表示创建成功。
- 返回时将 HTTP Header ‘Location‘ 值设置为https://api.server.com/books/new-created-book-id
- 客户端可以获得该条刚创建数据的 Unique ID，方便在需要进一步操作时使用
注意：POST API 不是一个数据安全和幂等性操作，如果客户端多次调用同样的 API 会导致多条数据被创建，这些数据除了 ID 不同其他属性都相同。
举例：
POST https://api.server.com/books
POST https://api.server.com/books/123456/comments
GET
一般用于读取数据，即获取资源。成功调用 GET API 会返回相应的数据。如果请求的数据不存在可返回404（Not Found）或者由于参数不正确的原因可以返回400（Bad Request）
- 客户端调用：客户端只要简单发送一个 HTTP GET 请求到相应的 URL 即可，请求URL 中可以带上有关参数用来对数据进行条件过滤，如：GET https://api.server.com/books?author=gause
- 服务端实现：服务端在收到相应的请求之后根据 URL 判断应该返回什么类型的数据，并且根据 URL 参数对数据进行过滤后在放在 Body 中返回给客户端。GET 可以返回一个集合，类似数组的形式。如：
如果客户端只请求一条数据 GET https://api.server.com/books/000，应该返回对应ID的数据即可：
注意：GET操作是数据安全和具有幂等性的操作，也就是多次调用GET应该返回相同的数据（期间没有修改操作的前提下），并且不会导致任何数据的破坏性修改。
API举例：
GET https://api.server.com/books/123456 GET https://api.server.com/books/123456/comments GET https://api.server.com/books/123456/comments/id001 GET https://api.server.com/books?author=gause
客户端调用：POST 调用方式几乎相同，比如要修改的数据是{id: "book-id-000", title: "Are your lights on", author: "Donald C. Gause"}客户端发送 HTTP PUT 请求到https://api.server.com/books。和POST不同的是，该操作会带上数据的 UID，用来定位具体要修改的这一条数据，方便后续操作。也有的设计会把ID放在URL中https://api.server.com/books/book-id-000，这样要修改的Body中的数据可以不用包含ID
服务端实现：如果更新成功 PUT API 应该返回200。如果 PUT 请求的 body 中没有任何信息则返回204, 如果id没有找到或id格式不正确，返回404。和POST不同的是该 API 没有必要在Header中更新刚创建数据ID URL，因为我们是在修改该条数据，其 ID 之前已经被客户的获取。
API举例：
PUT https://api.server.com/books/123456/comments/id001
{title: "Are your lights on"} 只包含部分要修改的数据上一篇：无法从命令行或调试器启动服务，必须首先安装Windows服务(使用installutil.exe)，然后用ServerExplorer、Windows服务器管理工具或NET START命令启动它
文章标题：HTTP Methods 和 RESTful Service API 设计
文章链接：http://soscw.com/index.php/essay/72974.html