restful

API开发近年来一直是一个非常有趣和具有挑战性的网页开发。互联网历史上的可扩展性在用户数量较少的时候并不是很重要，所以独立应用程序在很大程度上表现良好。然而，随着不同移动设备的大量涌现，今天的用户现在可以使用来自许多不同设备的相同应用程序，这导致开发人员需要扩展其应用程序。

就是说，创建一个通用的API是有意义的，可以轻松有效地扩展用户不断变化的需求，而不是开发不同的独立应用程序。因为创建API有几种不同的技术，所以没有设计API的真正标准或方法。但是，正确地设计API有几个商定的最佳做法。在没有实际标准的情况下，很难制定僵化的惯例。然而，将要讨论的大部分内容来自于将旧版应用程序移动到API模型的真实世界体验，或者从头开始创建新的API，这不仅具有弹性和稳定性，而且还具有可扩展性和快速性。

良好的API设计的重要性

没有人喜欢在网站上看到404错误，特别是当有人将博客文章或文章加入书签以备将来使用时。无论什么时候需要更改URL，用户都需要使用该URL，URL修改对SEO也不利。在没有正确抽象的情况下设计API可能需要稍后更改URL。虽然重定向可以解决这个问题，但这是一个避免重定向的SEO最佳做法。因此，在深入了解API设计之前设计标准是有意义的，并且在创建URL之前将其重点放在具体的细节和业务名称上。

在本系列中，我们将继续关注API开发的标准。本系列涵盖不同的技术标准，具体取决于具体的业务情况。假设API设计适用于基于HTTP的RESTful服务。

1,名词，无动词

API设计的第一条规则是在URL中使用名词。我们还应该使用HTTP动词来委派动词。例如，以下URL包含GET HTTP方法：

chanderdhall.com/gettrainings
由于HTTP支持GET方法，因此API需要以标准动词GET的方式进行设计，从而产生以下URL：

chanderdhall.com/trainings
原始网址有什么问题？虽然URL看起来很好，非常直观，但如果用户尝试使用不同的HTTP动词呢？假设用户想要使用以下URL：

POST chanderdhall.com/gettrainings

这显然是自我毁灭的。我们正在尝试添加培训，网址似乎给我们提供了错误的解释，这可能会将用户混淆到网址的实际使用中。这一规则适用于其余的动词。您可以创建一个HTTP DELETE请求，说明GetTrainings如下面的解决方案所示：

GET chanderdhall.com/trainings
POST chanderdhall.com/trainings
PUT chanderdhall.com/trainings
DELETE chanderdhall.com/trainings
您可能会注意到，无论动词是什么，URL都不会更改。

2.每个资源的两个基本URL

下一个标准是基于保持简单，愚蠢（KISS）原则。我们真的需要每个资源两个基本URL：一个用于多个值，一个用于特定值。在这个例子中，我们需要知道提供的多个培训，或者我们需要找到一个特定的培训，因为我们有必要的信息来检索它。同样，该信息可以是培训ID或名称。以下显示使用两个基本URL与四个HTTP动词的不同结果：

HTTP GET（读）
GET chanderdhall.com/trainings - 检索所有培训
GET chanderdhall.com/trainings/123 - 检索ID = 123的所有培训

HTTP POST（插入）
POST chanderdhall.com/trainings - 创建一个新的播客
POST chanderdhall.com/trainings/123 - 错误
为什么使用POST方法进行身份识别培训？这是因为ID是由数据库生成的，然后被传回给客户端。为什么要创建这种类型的功能，如果我们要做的是返回一个错误？这是因为我们正在设计一个API，我们不想给用户一个错误的印象，他的请求在实际上没有被接受。所以，重要的是我们需要处理错误。

HTTP PUT（更新）
PUT chanderdhall.com/trainings - 批量更新所有培训
PUT chanderdhall.com/trainings/123 - 如果存在，请更新特定培训。如果不存在，则会引发错误。这样做是因为我们不希望PUT方法执行插入，因为POST方法是插入的正确动词。
HTTP删除
GET chanderdhall.com/trainings - 删除所有培训。确保该人员被认证并被授权删除培训。
GET chanderdhall.com/trainings/123 - 删除具有授权权限ID = 123的培训。它应该检查特定训练是否真的存在。如果培训不存在，那么它应该抛出一个错误，指出没有找到资源。
3.关系

当您开发协作时，您的API应该非常直观。以下网址直观地表明，要求培训人员由ID为14的培训人员和ID为114的培训提供培训：

GET / trainers / 14 / training / 114
我们已经遍历了这个URL中的两个级别。一级是培训师，第二级是培训师提供的培训。
我们应该穿越多少级别？这是一个很难回答的问题，但是最好将它保持在最多三个级别，除非商业案例要求越高。

4 复杂性

强烈建议使用查询字符串来降低具有多个不同关联的URL的复杂性。以下显示了如何使用对用户有点复杂和不直观的查询字符串：

GET / trainers / 12 / training / 11 / zip / 75080 / city / richardson / state / tx
以下显示了更好的方式来编写查询字符串：

GET / trainers / 12 / training / 11？zip = 75080＆city = richardson＆state = tx
什么进入查询字符串？没有硬而快的规则。您可以使用域驱动设计方法将实体放在查询字符串（在本例中为“培训者”和“培训”）之前的常规URL中，并将值对象作为查询字符串的一部分添加（在这种情况下）邮政编码，城市和州）。虽然值对象类似于域驱动设计中的实体，但它们可能没有与其相关联的ID。在这种情况下，地址是一个值对象，假设我们的地址没有ID，那么该值对象的属性可以成为查询字符串的过滤条件。

这是普遍的法律吗？

不，这不对。这种技术可以在通用情况下有所帮助。但是，通常您的业务决定了过滤条件，但这是您可以偏离的。

我建议在URL中的父子关系中最多可以分三个级别。如果您的网址仍然很复杂，请考虑添加一个查询字符串。

5 错误格式

当我们没有明确定义格式时，错误格式化可能变得非常有趣。我认为一个错误格式是非常重要的，并且需要在公司中全面地具有特定的错误格式。让我们考虑一个错误格式，如下所示：

{
“error_type”：“应用程序错误”，
“error_details”：“＃500：内部服务器错误”
}
虽然这不是一个错误的错误格式，但有点难以使用。从客户端的角度来看，HTTP错误代码不是一个不同的字段，需要通过在“：”级别分割字符串“error_details”，然后将其与所有可能的HTTP代码进行比较来推断。在客户端级别有空间的错误和处理是不必要的和不需要的。这是我喜欢的另一种错误格式：

{
“http_code”：“401”，
“message”：“需要验证”，
“internal_error_code”：“123”，
“details_url”：http：// chanderdhall.com/wiki/errors/123
}
诸如“internal_error_code”等属性名称可以缩短，如“代码”。这些属性名称更长的原因是为了使它们也是不言自明的。在上面的示例中，401只是HTTP错误代码，123是一个内部错误代码详细信息，可以在details_url找到。这有一个额外的优势，使用户更好地了解错误。

关于应该支持多少个HTTP错误代码，这取决于你。约10个标准代码应该是足够的。我的建议是使用HTTP错误代码，使其符合标准。每当我们看到一个200错误，那么我们知道我们是成功的，所以API的用户知道关联的HTTP错误代码是典型的。

希望您喜欢API设计的最佳实践第1部分。如果您有任何问题，请给我发电子邮件，请通知我。在第2部分中，我们讨论版本控制，分页，部分响应，格式化结果，多个响应，搜索和超媒体。

随时访问我的博客相关文章。