总的来说，HTTP协议出现以来Web服务也就存在了。但是，自从云计算出现后，才成为实现客户端与服务和数据交互的普遍方法。
作为一名开发者，我很幸运能够在工作中使用一些仍然存在的SOAP服务。但是，我主要接触的是REST，这是一种基于资源的API和Web服务开发架构风格。在我的职业生涯中有很大一部分时间都参与了构建、设计和使用API 的项目。我见过的大多数API 都“声称” 是 “符合REST原则”的——意味着遵循 REST 架构的原则和约束。但是，我也曾遇到过一些让 REST 蒙羞的 API 例子，错误使用 HTTP 状态码、纯文本响应、不一致的模式、插入端点中动词...
因此我决定写篇文章分享一下，在设计 REST API 时的最佳实践。以下是关于设计优秀REST API 的一些建议、提示和指导，帮助您让消费者（以及开发人员）满意。
1. 学习 HTTP 基础知识
如果你想构建一个设计良好的REST API，那么你必须了解HTTP协议的基本知识。我坚信这将帮助你做出正确的设计选择。Mozilla Developer Network文档上关于HTTP概述是一个相当全面的参考资料，尽管如此，在REST API设计方面，以下是将HTTP应用于RESTful设计的简要说明：
-
HTTP具有动词（操作或方法）：最常见的是GET、POST、PUT、PATCH和DELETE。
-
REST以资源为导向，资源由URI表示：
/library/ -
端点（endpoint）是动词和URI的组合，例如：
GET: /books/ -
端点可以理解为对资源执行的操作。例如：
POST: /books/可能意味着“创建一本新书”。 -
高一层次来看，动词映射到CRUD操作：
GET表示读取，POST表示创建，PUT和PATCH表示更新，DELETE表示删除 -
响应状态由其状态码指定：
1xx 表示信息, 2xx 表示成功, 3xx 表示重定向, 4xx 表示客户端错误 和5xx 表示服务器错误
当然你还可以使用其他 HTTP 协议提供给 REST API 设计的功能 ，但这些都必须牢记在心里。
2. 不要返回纯文本
尽管并非强制规定的，但大多数REST API通常约定使用JSON作为数据格式。然而，仅返回包含JSON格式字符串的响应体是不够好的。您还应该指定Content-Type标头。它必须设置为application/json值。
在处理应用程序/编程客户端（例如，通过Python中的requests库与您的API交互的另一个服务/API）时，这一点尤为重要——其中一些客户端依赖于此标头来准确解码响应。
3. 不要在 URI 中使用动词
到目前为止，如果您已经理解了基本概念，那么您会开始意识到在URI中放置动词是不符合RESTful的，这是因为HTTP动词应该足以准确描述正在对资源执行的操作。
示例：假设您要提供一个端点来生成和检索一本书的封面。我将注意到:param 是一个URI参数（如ID或缩写）的占位符，你第一个想法可能是创建类似于这个的端点：
GET: /books/:slug/generateBookCover/
但是，在这里GET方法在语法上足以说明我们正在获取（“GET”）一本书的封面。所以，让我们只使用：
GET: /books/:slug/bookCover/
同样，对于创建新书的端点：
#Don’t do this
POST: /books/createNewBook/
#Do this
POST: /books/
4. 使用复数名词表示资源
我们应该使用 /book/:id/ (单数) 还是 /books/:id/ (复数)？我个人建议使用复数形式。为什么？因为它非常适合所有类型的端点。
我可以看到 GET /book/2/ 是没问题的。但是 GET /book/ 呢？我们是在获取图书馆里唯一的那本书、其中几本还是全部？为了避免这种模棱两可的情况，让我们保持一致（
标签：API,HTTP,GET,URI,REST,books,POST From： https://www.cnblogs.com/apibest/p/17559786.html