好的API设计对于那些试图完善API策略的团队来说是一个很重要的话题。一个设计良好的API的好处包括：改进的开发人员体验、更快的文档编制和更高的API采用率。 但是，好的API设计到底需要做什么呢？在本文中，我将详细介绍一些设计RESTful API的最佳实践。

设计良好的API的特性

通常，有效的API设计将具有以下特征： 1、易于阅读和使用：一个设计良好的API很容易使用，它的资源和相关操作可以很快被经常使用它的开发人员熟悉。 2、难以误用：实现和集成具有良好设计的API是一个简单的过程，因为有信息性的反馈，编写不正确的代码的可能性较小。 3、完整而简洁：一个完整的API将使开发人员可以针对公开的数据数据生成完整的应用程序。完整性通常随着时间的推移逐渐完善，大多数API设计人员和开发人员都是在现有API的基础上逐步构建的。

集合，资源及其URL

了解资源和集合 资源是REST概念的基础。资源是一个足够重要的对象，它本身就可以被引用。资源具有数据，与其他资源的关系以及对其进行操作以允许访问和操纵关联信息的方法。 一组资源称为集合。集合和资源的内容取决于团队和消费者需求。统一资源定位符（URL）标识资源的在线位置。 / users：一组用户 / users / username1：包含有关特定用户信息的资源
名词可以更好地描述网址 基本URL应该整洁、简单，以便使用产品的开发人员可以在其Web应用程序中轻松使用。较长且难以阅读的基本URL不仅不好看，而且在尝试进行重新编码时也容易出错。这些名词具有自我解释性，可以帮助开发人员了解从URL描述的资源类型。

使用HTTP方法描述资源功能 所有资源都有一组方法，可以对它们进行操作处理API公开的数据。 REStful API主要由HTTP方法组成，这些方法针对任何资源都有定义明确且独特的操作。以下是常用的HTTP方法的列表，这些方法为RESTful API中的任何资源或集合定义CRUD操作。

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

响应 提供反馈意见帮助开发人员成功 向开发人员提供良好的反馈，让他们了解产品的使用情况，对于提高采用率和留存率有很大帮助。每个客户端请求和服务器端响应都是一条消息，并且在理想的RESTful生态系统中，这些消息必须具有自我描述性。好的反馈包括对正确实现的肯定性验证，以及对错误实现的信息，这些错误可以帮助用户调试和纠正他们使用产品的方式。对于API，错误是提供API使用上下文的好方法。使错误与标准HTTP代码保持一致。不正确的客户端调用应该具有400类型错误。如果有任何服务器端错误，则必须将它们与500响应相关联。对资源使用的成功方法应返回200类型的响应。一般来说，使用API时有三种可能的结果：-

客户端应用程序的行为错误（客户端错误-4xx响应代码） API的行为不正确（服务器错误-5xx响应代码） 客户端和API正常运行（成功-2xx响应代码）
无论最终用户何时遇到使用API的障碍，让他们最终成功试用，将改善开发人员体验和防止API误用大有帮助。简洁明了的描述错误响应，在错误代码中提供足够的信息，供最终用户着手解决问题的原因。

GET请求示例 设计良好的API还需要提供示例，说明在成功调用URL时预期的响应类型。此示例应该简单且易于理解。使用API设计工具Eolinker中定义API，如下所示：

响应：

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

API设计入门

没有一种API设计方法适用于每个团队。以上只是建议，可以根据用户情况和要求使用或放弃建议。 API设计至关重要的主要原因之一是帮助最终用户使用API。他们的需求应该是设计和构建一个伟大的API的指南。 翻译：Eolinker——国内份额最大的API管理工具