[译]RESTful API设计指南 - 最佳实践

2018-12-10 本文已影响0人情衣

翻译自：https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9

Facebook, Google, Github, Netflix 以及其他一些科技巨头都让开发人员和产品有机会通过API使用他们的数据，并以此成为他们的平台。
即使你没有为其他开发人员和产品编写过API，拥有精美的API对你的应用来说也是非常必要的。
关于设计API的最佳方式，网上一直有争论。
API是一个接口，许多开发人员通过该接口与数据进行交互。设计良好的API总是非常易于使用，并使开发人员的生活非常顺利。API是开发人员的GUI(图形用户界面)，如果它令人困惑或不详细，那么开发人员将开始寻找替代方案或停止使用它。开发人员的经验是衡量API质量的最重要指标。

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

1.术语

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

Resource是某种东西的对象或表示，它具有一些与之相关的数据，并且可以有一组方法对其进行操作。例如。动物，学校和员工是资源，删除，添加，更新是要对这些资源执行的操作。
Collections是一组资源，例如，公司是公司资源的集合。
URL（统一资源定位符）是可以定位资源并且可以对其执行某些操作的路径。

2.API endpoint

让我们为拥有一些员工的公司编写一些API，以便了解更多信息。
/getAllEmployees 是一个API，它将响应员工列表。
几个围绕着Company APIs如下所示：

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

对于不同的操作，将会有大量其他API endpoint。所有这些都将包含许多冗余操作。因此，当API计数增加时，所有这些API endpoint 都将很难维护。

What is wrong?
URL应仅包含资源（名词）而不包含动作或动词。API路径 /addNewEmployee 包含操作addNew以及资源名称Employee。

Then what is the correct way?
/companies endpoint是一个很好的例子，它不包含任何动作。但问题是我们如何告诉服务器有关在公司资源上执行的操作。是添加，删除或更新？

这就是HTTP方法（GET，POST，DELETE，PUT）（也称为动词）扮演角色的地方。
API endpoint中的资源应始终为复数，我们通常可以在URL中传递id，来访问资源的一个实例。

方法	URL	描述
GET	/companies	应该获得所有公司的名单
GET	/companies/34	应该得到ID为34的公司信息
DELETE	/companies/34	应该删除ID为34的公司

在其他一些用例中，如果我们在资源下还拥有资源，例如，公司的员工，然后几个示例API endpoint如下：

方法	URL	描述
GET	/companies/3/employees	应该从公司3获得所有员工的名单
GET	/companies/3/employees/45	应该获得员工45的详细信息，该员工属于公司3
DELETE	/companies/3/employees/45	应该删除属于公司3的员工45
POST	/companies	应该创建一个新公司并返回创建的新公司的详细信息

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

结论：路径应包含复数形式的资源，HTTP方法应定义要对资源执行的操作类型。

3.HTTP方法（动词）

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

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

重要的HTTP方法如下：

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

4.HTTP响应状态码

当客户端通过API向服务器发出请求时，客户端应该知道反馈，无论是失败，传递还是请求错误。HTTP状态代码是一堆标准化代码，在各种情况下有各种解释。服务器应始终返回正确的状态代码。

以下是HTTP代码的重要分类：
2xx（成功类别）

200 Ok 表示GET，PUT或POST成功的标准HTTP响应。
201 Created 每当创建新实例时，都应返回此状态代码。例如，使用POST方法创建新实例时，应始终返回201状态代码。
204 No Content 表示请求已成功处理，但尚未返回任何内容。
DELETE就是一个很好的例子。
API DELETE /companies/43/employees/2将删除员工2。在返回值中，我们不需要API的响应主体中的任何数据，因为我们明确要求系统删除。如果有任何错误，例如数据库中不存在员工2，则响应代码将不是2xx成功类别，而是4xx客户端错误类别。

3xx（重定向类别）

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

4xx（客户端错误类别）
这些状态代码表示客户端已提出错误请求。

400 Bad Request 指出客户端的请求未得到处理，因为服务器无法理解客户端要求的内容。
401 Unauthorized 表示不允许客户端访问资源，并应使用所需的凭据重新请求。
403 Forbidden 表示请求有效且客户端已通过身份验证，但不允许客户端出于任何原因访问页面或资源。例如，有时不允许授权客户端访问服务器上的目录。
404 Not Found 表示请求的资源现在不可用。
410 Gone 表示已故意移动的请求资源不再可用。

5xx（服务器错误类别）

**500 Internal Server Error ** 表示请求有效，但服务器混乱，并要求服务器提供一些意外情况。
**503 Service Unavailable ** 表示服务器已关闭或无法接收和处理请求。大多数情况下，如果服务器正在进行维护。

5.字段名称惯例

您可以遵循任何套管约定，但要确保它在整个应用程序中保持一致。如果请求正文或响应类型是JSON，那么请关注camelCase以保持一致性。

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

所有这些操作都只是简单的对一个数据集查询。将不会有新的API集来处理这些操作。我们需要使用GET方法API附加查询参数。
让我们通过几个例子来理解如何实现这些操作。

Sorting 客户希望获得公司的排序列表，GET /companies endpoint 应该在查询中接受多个排序参数。
例如，GET /companies？sort = rank_asc会按升序排列公司。
Filtering 为了过滤数据集，我们可以通过查询参数传递各种选项。
例如，GET /companies?category=banking&location=india 将过滤公司列表数据与公司类别的银行和位置是印度。
Searching 在公司列表中搜索公司名称时，API endpoint应该是GET /companies?search=Digital Mckinsey
Pagination 当数据集太大时，我们将数据集划分为更小的块，这有助于提高性能并更容易处理响应。例如。 GET / companies？page = 23表示在第23页获取公司列表。

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

7.版本

当您的API被世界使用时，因为一些重大的变化升级API的时候，也会导致破坏现有产品或使用您API的服务。
路径中包含API的版本号就是一个比较好的方案，比如http://api.yourservice.com/v1/companies/34/employees，如果有任何重大更新，我们可以将新的API命名为v2或v1.x.x.