【翻译】API设计的最佳实践

最新推荐文章于 2024-09-26 17:23:32 发布

Mikemax

最新推荐文章于 2024-09-26 17:23:32 发布

阅读量130

点赞数

文章标签： json

原文链接：https://my.oschina.net/u/2422879/blog/2174001

版权

设计优秀API的特征

通常有效的API设计拥有下列特征：

易于阅读和使用：设计良好的API易于使用，并且经常使用的开发者可以很快速地记住其资源和相关操作。
很难被滥用实现和集成具有良好设计的API将是一个简单的过程，不太可能编写错误的代码。它提供了信息反馈，并没有对API的s使用者强制执行严格的指导。
完整而简洁最后，一个完整的API将使开发人员能够针对您公开的数据开发完整的应用程序。随着时间的API设计会变的完整，大多数API设计人员和开发人员会在现有API的基础上逐步构建。每一个公司和工程师在开发API时努力实时这个目标。

为了说明下面列出的概念，将以照片共享APP为例进行说明。该应用程序允许用户上传照片，使用拍摄这些照片的位置来描述照片以及描述与之相关的情感的标签。

Collections, Resources, and their URLs

理解resources和collections

资源是REST概念的基础。资源是一个非常重要的对象，可以自行引用。单个资源它包含数据、同其他资源的关系及方法。其中这些方法允许访问和操作相关信息。一组资源被称作集合。集合和资源的内容取决于您的组织和消费者需求。例如，如果您认为市场将从获取产品用户的基础的基本信息中获益，那么您可以将其作为集合或资源公开。统一资源定位符（URL）标识资源的在线位置。此URL指向API资源所在的位置。基本URL是此位置的一致部分。对于照片共享应用程序，我们可以通过相应的URL访问通过集合和资源公开有关使用该应用程序的用户的数据。 1./users 一个用户集合 2./users/username1 包含特定用户信息的资源

词更好地描述URL

基本URL应该整洁，优雅，简单，以便使用您的产品的开发人员可以轻松地在他们的Web应用程序中使用它们。一个冗长且难以阅读的基本URL，不仅难以查看，而且在尝试重新编码时也容易出错。名词应始终值得信赖。**没有关于保持资源名词单数或复数的规则，尽管建议将集合保持为复数。**为了保持一致性，在所有资源和集合中具有相同的多元性是一种很好的实践。保持这些名词的自我解释有助于开发人员了解从URL描述的资源类型，最终可以使他们在使用API时变得自给自足。回到照片共享应用程序，说它有一个公共API/users和/photos作为集合。注意它们都是复数名词吗?它们也是自我解释的，我们可以推断/users和/photos分别提供有关产品注册用户和共享照片的信息。

使用HTTP方法描述资源功能

所有资源都有一组方法可以对它们进行操作，以处理API公开的数据。REStful API主要包含HTTP方法，这些方法针对任何资源都有明确定义的独特操作：

+--------------+-----------------------+
|    方法      |    描述                |
+--------------+-----------------------+
| GET          | 用于检索资源的表示      |
| POST         | 用于创建新资源和子资源  |
| PUT          | 用于更新现有资源        |
| PATCH        | 用于更新现有资源        |
| DELETE       | 用于删除现有资源        |
+--------------+-----------------------+

保持动词不在您的URL中也是一个好主意。操作GET，PUT，POST和DELETE已经用于对URL描述的资源进行操作，因此在URL中使用动词而不是名词可能会使您的资源混乱。在照片共享应用中，以/users和/photos作为端点，API的最终用户可以使用上述RESTful CRUD操作直观地使用它们。

响应(Response)

提供反馈以帮助开发人员成功

向开发人员提供良好的反馈，告诉他们如何使用您的产品，这对提高产品的采用性和留存率大有帮助。每个客户端请求和服务器端响应都是一条消息，在理想的RESTful生态系统中，这些消息必须是自描述的。良好的反馈包括对正确实现的积极验证，以及对错误实现的信息错误，这些错误可以帮助用户调试和纠正他们使用产品的方式。对于API，错误是提供使用API的上下文的好方式。围绕标准HTTP代码纠正错误。不正确的客户端调用应该具有与之关联的400类型错误。如果存在任何服务器端错误，则必须将适当的500响应与它们相关联。用于资源的成功方法应返回200类型的响应。有很多响应代码。有关其他信息，请查看此REST API教程。通常，使用API时有三种可能的结果：

客户端应用程序行为错误(client error 4XX)
API行为错误（server error 5XX）
客户端和API正常工作（success -2XX）

只要他们遇到使用您的API的障碍，就可以让您的最终消费者获得成功，这将大大提高开发人员的体验并防止API误用。很好地描述这些错误响应，但要保持简洁和整洁。在错误代码中提供足够的信息，以便最终用户开始修复原因，如果您觉得需要更多信息，请提供其他文档的链接。

举例说明您的所有GET回复

精心设计的API还有一个例子，说明在成功调用URL时可以获得的响应类型。此示例响应应该简单明了，并且快速理解。一个好的经验法则是帮助开发人员准确理解成功的响应会在五秒钟内给出它们。回到照片共享应用程序，我们已经定义了/users和/photos URL。/users集合将提供已在数组中注册应用程序的所有用户的用户名和加入日期。您可以使用API设计工具在Swagger（OpenAPI）规范中定义API，如下所示：

responses:
	200:
		description: Successfully returned information about users
		schema:
			type: array
			items:
				type: object
					properties:
						username:
							type: "string"
							example: "kesh92"
						created_time:
							type: "dateTime"
							example: "2010-01-12T05:23:19+0000"

请注意最终用户可以从成功的GET调用中获得的数据类型和每个响应项中描述的示例。最终用户在JSON中收到的成功响应如下所示:

{
	“data”:[
		{
		“Username”:“example_user1”,
		“created_time":“2013-12-23T05:51:14+0000 ”
		},
		{
		“username”:“example_user2”,
		“created_time":“2015-3-19T17:51:15+0000 ”
		}
		….
	]
}

如果最终用户使用GET方法成功调用终点，则用户应获取上述数据以及200响应代码以验证正确的使用情况。同样，不正确的调用应产生适当的400或500响应代码及相关信息，以帮助用户更好地对集合进行操作。

请求(Requests)

优雅的处理复杂性

您尝试公开的数据可以通过许多属性来表征，这些属性可能对使用您的API的最终使用者有利。这些属性描述了基本资源，并隔离了可以使用适当方法操作的信息的特定资产。API应努力完善，并提供所有必需的信息，数据和资源，以帮助开发人员以无缝方式与它们集成。但完善意味着要考虑API的常见用例。可能存在许多这样的关系和属性，并且为每个关系和属性定义资源并不是好的做法。还应考虑资源公开的数据量。如果您尝试暴露很多，可能会对服务器产生负面影响，尤其是在负载和性能方面。上述情况和关系是API设计中的重要考虑因素，可以使用适当的参数进行处理。

您可以在查询参数中扫描属性并限制“？”后面的响应，或者使用path参数隔离客户端正在使用的数据的特定组件。

我们以照片分享应用为例。开发人员可以使用它来获取有关在特定位置共享的所有照片和特定主题标签的信息。您还希望将每个API调用的结果数限制为10，以防止服务器负载。如果想获取所有在Boston共享并且标记为winter的照片，请求如下：

GET /photos?location=boston&hashtag=winter&limit=10

注意现在如何将复杂性简化为与查询参数的简单关联。如果您想根据客户的请求提供有关特定用户的信息，则请求将是：

GET /users/kesh92

其中kesh92是users集合中特定用户的用户名，并将返回kesh92的加入位置和日期。这些只是您设计参数以实现API完成的一些方法，并帮助您的最终开发人员直观地使用您的API。最后，如有疑问，请将其删除。如果您对特定资源或集合的功能有了第二个想法，那么请将其留给下一次迭代。开发和维护API是一个持续的过程，等待来自正确用户的反馈可以在构建强大的API方面发挥很大作用，使用户能够以创造性的方式集成和开发应用程序。