9个REST API设计的基本准则 - 网站源码_资源分享

一般来说情况下，在工程项目合作开发操作方式过程中牵涉的API结构设计是选用 REST API 的商业模式，但并没制订两个严苛的、可认知的、可扩充的规范化，从长远规划来看，随着工程项目的不断插值，特别的在保证质量的情况下，REST API 就会出现偏转。因此提议在工程项目末期就建立严苛的API导则。

对个人觉得好的 API 导则可能将防止很多无谓的沟通交流，提高工程项目合作开发工作效率，USB这类就是文件格式。上面是工程项目合作开发操作方式过程中 9 个要要严格遵守的 REST API 导则。

1、选用HTTP方式突显西北侧象征意义

REST API 引导为插件的每一 CRUD 操作方式选用不同的HTTP方式。其中，有下列三种：GET、POST、PUT、DELETE和PATCH。与天然资源密切有关的西北侧的中文名称要与应用领域的操作方式有关的HTTP方式相关联。

// 不太好的结构设计 GET /get_articles POST /insert_articles PUT /modify_articles DELETE /delete_articles //提议的结构设计 GET /articles POST /articles PUT /articles DELETE /articles

2、状况码须根据API的统计数据结论得出

插件最重要的优点之一是端点的回到与适当的状况码有关。这意味著，当我们的结论是获得成功还是失利的时候，能用一种更形式化的方式来抒发想传递的统计数据。

比如，假如获得状况码200，则能立刻晓得API允诺的结论是获得成功的，不然，假如获得状况码400，结论是失利的。

重要的是要晓得原有的状况码，并晓得在什么情况下应用领域它们，因为回到消息可能将与这类状况码严重错误地关连在一起（这是很常用的），这对于恒定合作开发操作方式过程非常不亲善，会给合作开发者带来疑惑。

// 不太好的结构设计 { “status”: 200, “error”: {…} } // 提议的结构设计 { “status”: 200, “data”: […] }

一些常用的HTTP状况码包括：

200：获得成功的允诺，一般来说是GET201：建立后获得成功允诺，一般来说是POST204：获得成功的允诺，没回到任何内容，一般来说是PUT或PATCH301：永久性链接到另两个西北侧400：严重错误的允诺（应用程序应修正允诺）401：需经许可，凭证未被辨识403：明令禁止，凭证已拒绝接受但没权限404：找不到天然资源不存在410：该天然资源先前已存在，但现在不存在429：允诺太多，用于速率限制，并且应包含重试标头500：服务器严重错误，是通用的，值得一看的是其他500级严重错误503：服务不可用，其中重试标头有用的另两个服务

3、过滤、排序和分页支持

在插件中，过滤、排序及分页是常用的，这样有助于用户查找到需要的信息，同样也能减少服务器天然资源的消耗（统计数据量大的情况下不分页可能将会带来服务器天然资源的耗尽）。

GET /articles?title=api&cate_id=1 ：过滤、检索所有具有下列属性的文章列表：标题为api，类型id为1。GET /articles?limit=10&offset=0 ：分页，从0行开始回到10条。GET /articles?limit=10&offset=0&sort=asc&order=title ：排序，回到按中文名称升序排列的文章记录。

4、一致性西北侧结构设计

经常遇到的关于各种API合作开发的讨论之一就是如何结构设计西北侧？是选用单数还是复数。简而言之，希望在插件中保持API结构设计的一致性，为此，提议以复数形式来构建西北侧。

天然资源不会总是有两个结论，两个表可能将会有许多结论，即使它只有两个结论，并且将其转为单数形式，也很难保持路由中文名称格式的一致性。

// 不太好的结构设计 GET /article GET /article/:id // 提议的结构设计 GET /articles GET /articles/:id

5、用天然资源中文名称命名西北侧

谈到一致性，假如晓得路由负责处理天然资源上的操作方式，那么有必要直接用天然资源的中文名称来命名西北侧，这样当合作开发者选用API的时候，就晓得API在处理哪些实体统计数据。

比如，需要增加订单，则不能以 /articles 作为西北侧，那就非常糟糕了。

6、天然资源层级结构设计

假如需要访问天然资源有关的实体统计数据怎么办呢？为了体现这种层级关系，有两个方式能参考：

以西北侧分层结构设计以参数结构设计

上面以“作者”和“文章”的经典示例为例。

GET /authors/quintion/articles/rest-api-design GET /articles?author=quintion&title=rest-api-design

这些方式都是有效的，在很多平台上都已看到过它们。就对个人而言，认为选用查询字符串比扩充当前路径更简洁。插件扩充得越多，肯定会具有更大的层次结构，反过来，路由也会扩充。即使这样，它还是根据每一人的标准，选用最喜欢的一种。

7、版本控制

随着工程项目的插值，不可防止的是要有两个稳定且明确的API版本，且没严重错误和歧义。假设部署了API，并且有几个应用程序开始选用它，那么当需要从天然资源中添加或删除更多统计数据时，会发生什么情况？可能将会在选用USB的外部服务上产生严重错误。这就是为什么相关联用领域程序要有具有版本控制的原因。

有三种方式，对个人是URI版本的支持者，在该版本中，将在西北侧中明确拥有路由的版本。

// URI 版本 v[x] GET /v1/news GET /v2/articles

8、缓存机制

高速缓存是一种能提高API速度和降低天然资源消耗的强大工具之一，其原理就是对相同结论的允诺，减少对统计数据库的操作方式。有多种方式能帮助实现缓存系统，其中之一文件缓存，如 Redis。

当然实现缓存机制一般来说也会带来成本，原则就是需要问一下：信息是动态的还是静态的？假如是动态的，信息多久更改一次？

重要的是要晓得缓存中有很长时间的信息，这可能将会由于长时间保留信息而导致API的严重错误结论，提议缓存时间结构设计得短一点。

9、结构设计文件格式

文件格式是工程项目合作开发和协作最好的工具之一，也是很多研发人员最讨厌的。在这种情况下，文件格式化的API是必不可少的，以便选用API的用户能理界面的几个重要方面，包括可访问性、响应、允诺、示例。

可访问性：界面的位置和交互是最重要的特征之一，不想合作开发者两个操作方式手册文件格式。响应和允诺：提供的信息要考虑任何天然资源可能将产生的所有可能将结论以及如何选用它们。示例：提供如何选用USB的示例非常重要，即使它是两个能在控制台中执行并从中获得响应的bash脚本。好在现在有很多有关的工具（Swagger）来降低合作开发者写文件格式的时间同时构建两个完善的API文件格式中心，包括详细的说明、调试示例等。