设计有效API的四个原则
我们在微服务时代。组织正在将web应用程序分解成小型、独立的云服务，这些云服务可以无缝地相互通信。API是这个架构的关键，因为这些服务之间的大部分数据交换都是通过API请求进行的。
API(应用程序编程接口)概述了应用程序将用来与其内部组件以及其他应用程序进行通信的一组规则。如果您正在构建一个应用程序，公开您的应用程序的API是有意义的，并且以一种使开发人员更容易与其他应用程序一起使用的方式来设计它们。
虽然没有正式的指导方针或标准来管理如何构建API，但是有一些原则可以帮助您以最普遍接受的方式开发API。大多数想法可以归入以下四个API设计原则:
在本文中，我们将讨论API设计的四个基本原则:
使用普遍接受的通用标准构建API
让你的回答易于理解和消费
保护您的API
有好的文档支持
1.使用普遍接受的通用标准构建API
大多数云应用程序都采用REST作为通过API请求传输数据的首选方法。休息已经存在很长时间了。有些实践效果很好，并且仍然被广泛使用，而有些则不然。让我们看看REST API设计中一些普遍接受的标准。
a.遵循请求路径的基本约定
请求路径应该指定正在发出的请求，并且应该以一种容易理解的方式来定义，不要留下任何混淆的空间。
使用资源名称
向请求路径添加动词是多余的，因为请求的类型(例如，得到, 邮政)清楚地定义了这一点。在API路径中只使用资源名，以避免任何额外的文本。
Bad:
/api/create-products
Good:
/api/products
使用复数形式
复数形式可用于管理单个项目和集合。单数形式的使用不能给出一个概念，如果有多个项目，导致混乱。同时拥有单数和复数形式将会使你的API请求列表翻倍。用下面的方法只使用复数形式，这样要求就清晰直观了。
Bad:
/api/product
Good:
/api/products
/api/products/:product_id
使用嵌套层次结构
嵌套有助于轻松获取相关项和子项。它还向用户清楚地表明了这种关系。
Bad:
GET /products/
GET /product-reviews
Good:
GET /products/:product_id/reviews
PUT /products/:product_id/reviews/:review_id
b.使用JSON作为交换格式
用JSON。它轻便灵活。它很容易被各种渠道消费，是一种广泛使用的格式。您也可以使用其他格式，比如XML、CSV和HTML，但是JSON胜过所有这些格式，因为它被广泛接受，可读，并且提供了简单的数据执行。设置"内容类型": "应用程序/json“在标题中为您的请求和响应。
c.版本API
当发布新的特性、变化或错误修复时，确保你的API版本化，并清楚地列出重大变化。这确保了您的更改不会影响用户的实现。做到这一点的标准方法之一是使用语义版本控制.
此外，对于所有版本，在基本URL后面使用版本号。这最不可能影响用户已经使用的端点的相对路径。
示例:
http://api.domain.com/v1/products
d.提供过滤、分页、排序和搜索数据的方法
数据库会变得非常大。你的API应该提供一些方法，允许用户缩小到他们所需要的范围，而不是一下子全部返回，否则很快就会耗尽他们的带宽，甚至使你的系统瘫痪。
用户可能需要过滤选项，以便从庞大的数据集中获取所需的数据。您可以通过请求提供多种方式来过滤数据。
示例:允许用户按类别提取产品:
/v1/products?query={categories: ["category1", "category2"]}
提供对响应进行分页的能力，因此即使是响应的用户也可以获取集合中的数据。这可以通过使用跳跃和'限制参数。
示例:
/v1/products?skip={skip_value}&limit={limit_value}
允许用户按照自己选择的顺序获取项目。提供基于各种字段(如日期、价格、名称等)对项目进行排序的方法。
示例:
/v1/products?sort=-price,updated_at
通过允许用户对所有字段的所有值执行全文搜索，为用户提供快速搜索相关数据的方法。
示例:
/v1/products?text={{search}}
2.让你的回答易于理解和消费
这可能是你的API中最重要的部分。开发人员使用API的难易程度在很大程度上取决于API响应的结构化程度和便利性。只要做好几件事，就能确保响应符合标准。
a.使用标准HTTP响应代码
HTTP提供了状态代码，您的API可以使用这些代码来告诉用户刚刚执行的请求发生了什么。这也有助于他们轻松了解API请求是成功还是失败。您可以将代码范围用于常见响应:
信息:100–199
成功:200–299
重定向:300–399
客户端错误:400–499
服务器错误:500–599
b.定义适当的响应主体
主体中的资源应该有适当的元数据，并且应该根据路径进行包装。对于包含多个单词的JSON键，可以使用连字符(-)、下划线(_)或大写字母。使用任何一个，并在所有回答中保持一致:
示例:
{
"users": [{
first_name: "John",
last_name: "Doe",
…
}, {
first_name: "Jane",
last_name: "Doe",
…
}],
"skip": 0,
"limit": 20,
}
c.有清晰的回复标题
定义适当的响应头有助于提供关于服务器行为的适当信息。如果你要对外公开你的API，支持CORS(跨源资源共享)头是很重要的。缓存头帮助用户确定数据是由源服务器还是缓存服务器提供的。您也可以使用“X-Request-Id: {{TRACE_ID}}”表头在回应。它有助于在调试时跟踪请求的整个生命周期。
d.删除不必要的响应标头
并非所有标题都是必需的。您可以删除不必要的响应头，如“Server”、“X-Served-By”或“X-Powered-By”，并为您的用户节省少量带宽。
3.保护您的API
使用SSL/TLS来保护您的所有端点和资源。没有例外。客户端和服务器之间的通信应该总是保密的，因为它可能涉及敏感数据。SSL/TLS确保您发送和接收的数据是加密的和安全的。
为了防止您的API受到不必要的滥用和攻击，应该有一定的限制。为用户提供一种明确的方式来了解这些限制，方法是使用限制标题，如“x-税率限制", "剩余x-税率限制“，和”x-rate limit-重置".
4.有好的文档支持
公开你的API文档。避免pdf。避免认证背后的文档。这使得很难找到你的文档，甚至用户很难搜索相关内容。
你的API文档应该引用你所支持的所有API版本。并且它应该明确地调用突破性的变化。
文档应该提供一个概述(包括基本约定、基本URL等)。)并列出错误代码和可能的用例。它还应该涵盖整个请求-响应周期。
为了让读者更容易使用您的API，通过提供简单的复制粘贴url的方法或通过提供curl示例，使端点易于使用。或者更好的策略是提供Postman集合或OpenAPI规范，这样用户就可以用他们自己的方式尝试你的API。
构建良好API的10个最佳实践
有了API设计和集成的灵活性，成为一名API开发者没有比现在更激动人心的时刻了。然而，随着这么多创建API的新技术和方法的出现，问题来了，“什么是好的API？”
虽然API创造的增加对多个领域的企业都有很多好处，但也为低质量的API生产提供了更多的空间。
构建API时遵循十个最佳实践对于确保API的高质量和高价值至关重要。
1.用JSON接受和响应
开发API的一个最重要的方面是确保您使用的是标准的数据格式。通过使用JSON，您可以确保来自您公司内部或外部的任何学科的开发人员都能够使用API并与之集成，而无需单独为该软件学习新的特定语言。
如果您创建一个API，总是从接受JSON中的请求开始，因为这是当今开发人员中最流行的请求类型。
2.在端点路径中使用名词而不是动词
在端点路径中使用名词而不是动词将使开发人员更容易理解他们将请求发送到哪里。使用名词代替动词还可以创建更直观的API端点，使用户比以前更容易地发送和接收数据。
例如，“上传”是一个动词，而“照片”是一个名词，这样可以更好地理解每个端点路径应该发送什么类型的请求或响应。使用这样的词也有助于创建清晰的文档，因为人们可以在API文档中引用这些类型的名称，而不是回忆其他地方列出的抽象命名的函数或命令。
3.对Rest APIs使用版本控制
假设您正在创建您的应用程序接口。在这种情况下，有必要使用一个版本控制系统，允许开发人员使用任何以前或当前的版本来访问他们需要的信息。有许多方法可以做到这一点，其中一种方法可能比其他方法更适合您的公司，但是版本控制的本质不是您如何做，而是您到底要做什么。
确保每个新的端点路径都包含其唯一标识符并提供与旧请求的向后兼容性也很有帮助，这样无论用户的代码是在哪个时期编写的，用户都可以更容易地访问。
版本控制系统，如语义版本控制通过对如何更新系统制定明确的规则，有助于确保向后兼容性。
4.在端点上使用逻辑嵌套
嵌套端点是帮助开发人员更容易理解和使用API的另一种方式。通过将相关的请求嵌套在一起，您可以减少开发人员访问他们的请求数据所必须采取的步骤。
例如，与其有多个端点路径，如“customers/list”和“customer/123”，不如有一个包含这两个端点的路径，称为“/customers”这将允许来自公司任何部分的用户或公司外部的用户只使用一个端点请求过滤的客户列表，而不是两个单独的端点，因为它们嵌套在不同的级别下。
逻辑嵌套还可以提高安全性，因为所有用户活动都是从这个中心点开始，然后再深入到更敏感的数据。
5.使用身份验证方案保护端点
就API安全性而言，无论开发人员和用户是否在您公司的网络上，身份验证方案都是保护他们数据的最佳方式。在API开发中所有可用的不同类型中，OAuth已经成为大大小小的公司使用最广泛的类型之一。这是因为它让您可以使用跨平台的基于令牌的系统来完全控制谁可以访问什么信息。
这还允许在请求前和请求后提供最大程度的保护，并增加用户权限的灵活性，而不会损害创建API时所需的整体安全措施。
6.准备好处理错误
错误是API开发周期中常见的一部分，任何希望影响其API的公司都应该小心处理。每个错误必须包含足够的信息，以便开发人员能够理解它，同时如果他们需要您的团队提供额外的帮助来快速解决问题，也要提供一个解决方法。使用错误代码是改进调试过程的一个很好的方法，可以快速修复用户体验。
为了防止错误，请使用以下工具时髦的，这将允许您在上线之前测试您的代码，以便可以解决或完全防止这些错误，而不是等到上线后用户已经开始报告它们为错误。此外，每个端点路径应该尽可能包含自己的唯一标识符和向后兼容性。这将有助于确保接收到的请求被正确定向，即使后来出现问题、将来的更新或版本更改。在您的API之旅中，您可能会遇到许多不同种类的错误，比如错误的请求。有许多教程可以帮助您学习错误处理，以确保API用户在启动时有积极的体验。
7.使用分页
分页是开发API的另一个重要部分，许多开发人员经常忘记在某个时候包含它。
分页允许更容易地访问大量数据，因为它将信息分成更小的组，而不是要求用户在一次请求中下载所有内容。这有时可能包含比您预期更多的信息，如果您的设备无法支持如此沉重的负载，会导致崩溃和其他问题。
通过用分页来分割请求，您可以确保您公司的资源和开发人员的资源在标准用例中不会过载。
8.使用强大的安全协议
无论您为开发人员创建一个合适的API做了多少规划和工作，如果您的服务器经常被请求过载或被网络攻击.
为了尽可能避免这种情况的发生，请确保任何希望开发API的公司都明白，当事情随着技术的不断发展而不可避免地发生变化时，他们现在和将来都需要什么类型的安全协议。对于您的项目，总是推荐使用安全的SSL。为了简单起见，SSL可以添加到头部代码中，也可以内置到后端。
这可以包括从围绕每台服务器上的敏感信息放置的防火墙到自动进行的每日备份，以便数据永远不会因人为错误或其他技术事故而丢失。
9.缓存数据以提高性能
为了让您的API发挥最佳性能，您需要确保每个请求都尽可能地快速高效。
缓存允许提取已经发出的请求，而不需要来自开发人员设备的新调用。这是因为数据已经被检索并存储在服务器端的内存中。
这可以包括从保存开发过程中使用的图像或其他大文件的所有内容。它们不需要在每次另一个用户发出类似请求时通过记录以前收到的结果信息来再次下载，这将有助于加快未来呼叫的速度。
10.限速
速率限制是API设计的另一个方面，可能需要一些规划才能正确。
这个特性允许您的公司和开发人员使用您的API来保持请求数量之间的平衡，同时不会使处理这些请求的系统任何部分过载。在制定速率限制时，通过仔细考虑每天的时间或其他窗口，您可以确保不会出现一个开发人员的请求覆盖另一个开发人员的请求的情况。这可能会导致数据丢失或任何一方崩溃，因为您由于被过量信息超载而推得太远了。
