RESTful API设计指南-最佳实践

Facebook，Google，Github，Netflix和其他少数技术巨头给开发人员和产品提供了通过API使用数据的机会，并成为了他们的平台。
即使您没有为其他开发人员和产品编写API，使用精心制作的API对于您的应用程序也总是非常健康。

关于设计API的最佳方法，互联网上有很长的争论，这是最细微的差别之一。没有为此定义任何官方指南。

API是一个接口，许多开发人员可通过该接口与数据进行交互。设计良好的API总是非常易于使用，并使开发人员的生活非常顺利。API是开发人员的GUI，如果感到困惑或冗长，则开发人员将开始寻找替代方案或停止使用它。开发人员的经验是衡量API质量的最重要指标。

API就像是艺术家在舞台上表演，其用户是观众

 

1）术语

以下是与REST API相关的最重要的术语

• 资源是事物的对象或表示，它具有一些关联的数据，并且可以使用一组方法对其进行操作。例如，动物，学校和雇员是资源，删除，添加，更新是对这些资源要执行的操作。
• 集合是资源集，例如，公司是公司资源的集合。
• URL（统一资源定位符）是可用来定位资源并对其执行某些操作的路径。

2）API端点

让我们为拥有一些员工的公司写一些API ，以了解更多信息。
/getAllEmployees是一个将响应雇员列表的API。公司周围的其他API 如下所示：

• /addNewEmployee
• /updateEmployee
• /deleteEmployee
• /deleteAllEmployees
• /promoteEmployee
• /promoteAllEmployees

诸如此类的大量其他API端点将用于不同的操作。所有这些将包含许多多余的动作。因此，当API数量增加时，所有这些API端点都将难以维护。

怎么了？
该URL仅应包含资源（名词）而不是动作或动词。API路径/addNewEmployee包含操作addNew 以及资源名称Employee。

那正确的方法是什么？
/companies端点是一个很好的示例，其中不包含任何操作。但是问题是我们如何告诉服务器要在companies资源viz 上执行的操作。是否添加，删除或更新？

这就是HTTP方法（GET，POST，DELETE，PUT）（也称为动词）发挥作用的地方。

该资源在API端点中应始终为复数形式，并且如果我们要访问该资源的一个实例，则可以始终在URL中传递ID。

• 方法GET路径/companies应获取所有公司的列表
• 方法GET路径/companies/34应获取公司的详细信息34
• 方法DELETE路径/companies/34应删除公司34

在其他一些用例中，如果我们在某个资源下拥有资源，例如公司的雇员，则样本API端点很少是：

• GET /companies/3/employees 应该从公司3获取所有雇员的名单
• GET /companies/3/employees/45 应该获取属于公司3的员工45的详细信息
• DELETE /companies/3/employees/45 应该删除属于公司3的员工45
• POST /companies 应该创建一个新公司并返回创建的新公司的详细信息

API现在不是更加精确和一致吗？😎

结论：路径应包含多种形式的资源，并且HTTP方法应定义对资源执行的操作的类型。

3）HTTP方法（动词）

HTTP定义了几套方法，这些方法指示对资源执行的操作的类型。

URL是一个句子，其中资源是名词，而HTTP方法是动词。

重要的HTTP方法如下：

1. GET方法从资源请求数据，并且不应产生任何副作用。
   例如，/companies/3/employees返回公司3中所有员工的清单。
2. POST方法请求服务器在数据库中创建资源，通常是在提交Web表单时。
   例如，/companies/3/employees创建公司3的新雇员。  这
   POST是非幂等的，这意味着多个请求将产生不同的影响。
3. PUT方法请求服务器更新资源或创建资源（如果不存在）。
   例如，/companies/3/employees/john将请求服务器更新或创建（如果不存在）公司3下雇员集合中的john资源是幂等的，这意味着多个请求将具有相同的效果。
   PUT
4. DELETE方法请求应从数据库中删除资源或其实例。
   例如，/companies/3/employees/john/将请求服务器从公司3下的雇员集合中删除john资源。

还有一些其他的方法，我们将在另一篇文章中讨论。

4）HTTP响应状态码

当客户端通过API向服务器提出请求时，客户端应该知道反馈，无论是失败，通过还是请求错误。HTTP状态代码是一堆标准化代码，在各种情况下都有各种说明。服务器应始终返回正确的状态代码。
以下是HTTP代码的重要分类：

2xx（成功类别）

这些状态码表示服务器已接收并成功处理了请求的操作。

• 200 Ok标准的HTTP响应，表示GET，PUT或POST成功。
• 201已创建每当创建新实例时，都应返回此状态代码。例如，使用POST方法创建新实例时，应始终返回201状态代码。
• 204 No Content表示请求已成功处理，但未返回任何内容。
  删除就是一个很好的例子。
  API DELETE /companies/43/employees/2将删除雇员2，并且作为回报，我们明确要求系统删除，因此API的响应正文中不需要任何数据。如果有任何错误（例如如果employee 2数据库中不存在），则响应代码将不是，2xx Success Category而是4xx Client Error category。

3xx（重定向类别）

• 304 Not Modified表示客户端已经在其缓存中包含响应。因此，无需再次传输相同的数据。

4xx（客户端错误类别）

这些状态代码表示客户端提出了错误的请求。

• 400错误的请求表示客户端的请求未处理，因为服务器无法理解客户端的要求。
• 401 Unauthorized表示不允许客户端访问资源，应使用所需的凭据重新请求。
• 403禁止表示请求有效且客户端已通过身份验证，但由于任何原因不允许客户端访问页面或资源。例如，有时不允许授权的客户端访问服务器上的目录。
• 找不到404表示请求的资源现在不可用。
• 410已消失表示已被有意移动的请求资源不再可用。

5xx（服务器错误类别）

• 500 Internal Server Error表示请求有效，但是服务器完全混乱，要求服务器提供某些意外条件。
• 503服务不可用表示服务器已关闭或无法接收和处理该请求。通常，如果服务器正在进行维护。

5）字段名称大小写约定

您可以遵循任何大小写约定，但是请确保在整个应用程序中保持一致。如果请求正文或响应类型为JSON，则请遵循camelCase保持一致性。

6）搜索，排序，过滤和分页

所有这些动作仅是对一个数据集的查询。没有新的API集可以处理这些操作。我们需要在查询参数中附加GET方法API。
让我们用几个示例来了解如何实现这些操作。

• 排序如果客户想要获得公司的排序列表，则GET /companies端点应在查询中接受多个排序参数。
  例如，GET /companies?sort=rank_asc将按升序对公司进行排序。
• 过滤为了过滤数据集，我们可以通过查询参数传递各种选项。
  例如，GET /companies?category=banking&location=india将使用“银行”的公司类别以及位置在印度的公司列表数据进行过滤。
• 搜索在公司列表中搜索公司名称时，API端点应为GET /companies?search=Digital Mckinsey
• 分页当数据集太大时，我们将数据集分成较小的块，这有助于提高性能并更容易处理响应。例如。GET /companies?page=23意味着在第23页上获得公司列表。

如果在GET方法中添加许多查询参数会使URI太长，则服务器可能会以414 URI Too longHTTP状态进行响应，在这种情况下，参数也可以在方法的请求主体中传递POST。

7）版本控制

当您的API受到全世界的欢迎时，以一些重大更改升级API还会导致使用您的API破坏现有的产品或服务。

http://api.yourservice.com/v1/companies/34/employees是一个很好的例子，该路径中包含API的版本号。如果有重大更新，我们可以将新的API命名为v2或v1.x.x

这些准则是根据我的开发经验编写的。我很想知道您对上述指针的看法。请发表评论，让我知道！