在很多情况下，在开发REST API（或尝试使用这种模式）时，我们并不重视建立干净，可理解且可扩展的体系结构的重要性，但从长远来看，随着应用程序的增长，这将产生巨大影响。
假设现在是时候向用户公开我们正在开发的界面了，那么您如何确定他们了解您尝试在界面中传输的内容呢？对使用该应用程序的用户的理解不仅是相关的，而且对于您的团队和将来将要使用该应用程序的人们来说也是可以理解的。从架构的开始就建立一个每个人都会尊重的基础是至关重要的。
这些是我认为最重要的几个方面：
1.使用HTTP方法赋予端点含义REST API鼓励我们对应用程序的每个CRUD操作使用HTTP方法。其中，我们有以下几种：GET，POST，PUT，DELETE和PATCH。与资源关联的端点的名称必须带有与所应用的动作有关的HTTP方法。
- GET /get_cats
- POST /insert_cats
- PUT /modify_cats
- DELETE /delete_cats
GET /cats
POST /cats
PUT /cats
DELETE /cats
2.状态代码必须符合我们API的结果。我们应用程序最重要的品质之一就是端点的返回与相应的状态码有关。这意味着一旦我们的结果成功或失败，我们就可以以更具描述性的方式关联我们想要传达的信息。
例如，如果我们获得状态200，则可以立即知道我们的结果是成功的；否则，如果我们获得状态400，则结果将失败。
重要的是要知道现有的状态码，并知道我们需要在每种情况下应用它们，因为返回消息可能会错误地与某些状态码相关联（这很常见），这对于正常工作非常有害。应用程序，因为它会使我们的REST API的开发人员和消费者用户感到困惑。
// Bad, we return status code
200 (Success)
// associated with an error object
{ "status": 200, "error": {...}}
// Good
{ "status": 200, "data": [...]}
3.筛选，排序和分页支持在任何使用我们的API的应用程序中，很多情况都希望以某种方式从我们的服务中消耗更少的资源，这可能是由于性能，搜索系统，信息过多或仅仅是显示我们资源中的某些特殊内容。
过滤，排序和分页，除了扩展API的功能外，还有助于我们减少服务器资源的消耗。
假设端点返回了数百万个结果，那么我们的服务器会如何反应？（他肯定会哭泣并崩溃）。
· GET / cats？race = misumisu＆age = 1
->过滤，检索所有具有以下属性的猫：种族为misumisu，年龄为1。
· GET / cats？limit = 15＆offset = 0
->分页，从0行开始返回15行。
· GET / cats？limit = 15＆offset = 0
->排序，返回按名称升序排列的行。
4.多个端点关于各种API开发的日常讨论之一，是确定是使用单数还是复数来构造端点。简而言之，我们希望在应用程序中保持牢固的一致性，为此，我的建议是将端点构建为复数形式。
资源将不会总是有一个结果，一个表可能会有很多结果，即使它只有一个结果，并且我们将其放在单数形式，我们也不会保持路由名称格式的一致性。
"一致性是成功的关键"
- GET /cat
- GET /cat/:id
GET /cats
GET /cats/:id
5.使用资源名称命名端点说到一致性，如果我们知道路由负责处理资源上的操作，则必须直接用资源名称来命名它，因此当一个人使用我们的API时，他们将了解他们正在使用的实体上。
例如，如果您要归还猫，则不会将端点称为/ dogs dog。
6.资源层次如果我们要访问属于资源的紧密链接的实体怎么办？
为了显示这种关系，我们有两个选择：
· 在我们的作者端点中分层地附加文章
· 请求参数
让我们以"作者"和"文章"的经典示例为例。
GET /authors/betoyanes/articles/create_cat_memes
GET /articles?author=betoyanes&name=create_cat_memes
这些方法是有效的，我在许多项目中都已看到它们。就个人而言，我认为使用查询字符串比扩展当前路径更干净。应用程序扩展得越多，我们肯定会具有更大的层次结构，反过来，路由也会扩展。即使这样，它还是根据每个人的标准，所以使用最喜欢的一个！
7.版本控制随着我们的发展，不可避免的是要有一个稳定且确定的API版本，且没有错误和防弹。假设我们部署了API，并且有多个客户端开始使用它，那么当您需要在资源中添加或删除更多数据时，会发生什么情况？您可能会在占用我们接口的外部服务上生成错误。这就是为什么对我们的应用程序具有版本控制机制至关重要的原因。
有几种方法，但是我是版本化URI的支持者，在该版本中，我们将在端点中明确拥有路由的版本。
// URI versioning v[x] syntax
GET /v1/cats
GET /v2/dogs
8.缓存高速缓存是一种可以提高API速度和降低资源消耗的强大工具之一，其思想是不要继续多次向您的数据库请求相同的请求，如果它继续获得相同的结果。有多种服务可以帮助我们实现此系统，其中，Redis是我的最爱之一。
我们肯定听说过实现缓存功能通常会带来成本，而且也不例外。让我们问以下问题，信息是动态的还是静态的？如果是动态的，信息多久更改一次？
重要的是要知道缓存中有很长时间的信息，这可能会导致通过长时间保留信息而导致API的错误结果，建议使用较短的缓存时间。
9.文档文档是我们最好的武器之一，也是许多人最讨厌的武器。在这种情况下，文档化的API是必不可少的，以便使用我们的用户可以理解我们界面的几个重要方面，包括可访问性，响应，请求，示例。
· 可访问性：界面的位置和访问权限是最重要的品质之一，我们不希望向客户提供how_to_use.txt。在云上公开我们的文档，每个人都可以看到，这是我们可以做的最方便的事情。
· 响应和请求：我们提供的信息必须考虑任何资源可能产生的所有可能结果以及如何使用它们。
· 示例：提供示例说明如何使用我们的界面非常重要，即使它是我们可以在控制台中执行并从中获得响应的bash脚本。
结论请记住，我们的API是我们暴露以使用后端服务的接口，因此请牢记这一点，重要的是应用最佳的原则，以便使用和使用它的人们都喜欢。
尽管我们正在开发个人项目，但是我们需要尝试应用我们考虑的最佳原则，以便我们在进入开发团队或项目时可以得到实践。
希望本文对您有所帮助，并为您的REST API良好做法集合增加了一些原则！您还有其他原则要补充吗？请在评价部分留下您的意见！
(本文由闻数起舞翻译自John Fajardo的文章《9 Best Practices for REST API Design》，转载请注明出处，原文链接：https://medium.com/weekly-webtips/9-best-practices-for-rest-api-design-7fb0b462099b)
,
