API-设计的最佳实践.docxVIP

API 设计的最佳实践如果你重新思考了某个资源或集合的功能，应该把它放入下一个迭代中。开发和维护API是一个持续的过程，等待正确的用户反馈可以构建一个健壮的API，以帮助用户以创造性的方式集成和开发应用程序。作者：Keshav Vasudevan来源：/archives/7294036大数据|2016-12-27 08:49javascript:favorBox(open);?收藏 javascript:;?分享 /acthappy?wzh推广 | 令人窒息的奖品等你—2016最权威的全球开发者调研优秀的API设计话题，在很多团队涌现，这些团队正在努力完善他们的API策略。在之前发布的博客上，我简要的讨论了API设计的重要性。一个设计良好的API应该包含那些好处：你的API应该能提高开发者经验、方便的快捷文档和高可用性。但优秀的API设计究竟应该怎么做?在这个博客中，我将详细的介绍一些RESTful API的最佳设计。一个设计良好的API的特点一般来说，一个有效的API设计遇有以下特点：易于阅读和使用。一个设计良好的API应该很容易被使用，其资源和相关操作能够快速的被使用它的开发人员记忆。难以误用。设计良好的API实现和集成将是个简单的过程，写出错误代码将变得不太可能。没有严格按照API开发指南的终端用户将会得到详实的信息反馈。完整又简洁. 最后，一个完整的API应该具有成熟的应用防止你的数据被泄露。API完整性会随着时间的推移而改变，大多数的API设计人员和开发人员都应在现有基础上逐步构建新的API。这是每一个使用API的工程师或公司都必须坚持的理念。为说明下面列出的概念， 我会以一个照片分享的应用程序举例。 该应用程序允许用户上传照片， 以拍摄地点和心情标签描述照片特征。集合，资源及其网址了解资源和集合资源是REST概念的基础。 一条资源是一个重要对象，它本身可以被引用。 一条资源含有数据，与其他资源的关系，以及操作方法，以允许访问和处理相关信息。一组资源被称为一个集合。 集合和资源的内容取决于你的组织和消费者的需求。 例如，如果你认为，市场获得了你的产品用户群的基本信息会受益， 那么，你就可以将此作为集合或资源。统一资源定位器(URL)确定了资源的在线位置。 URL指向你API资源存在的位置。 基URL是这个位置的一致部分。在照片分享应用一例中， 我们可以公开用户数据，只要用户通过集合和资源使用该应用程序， 经由适当的URL访问。/users：用户的集合。/users/username1：一个特定用户的信息资源。名词化的URL更好URL应该是整洁、优雅和简单的，这样开发人员更易在他们的web程序中使用你的产品。 很长且难以理解的URL不仅看起来很糟糕，而且在记录时容易出现错误。所以使用名词应该是很好的。没有规定让资源名词使用单数或复数，但是在如果是集合的话使用复数无疑很好的。 具有相似的资源和集合分别保持它们的一致性是较好的做法。保持这些名词的自解释性，有助于开发人员了解从URL描述的资源, 这最终会使他们使用你的API。回到照片分享应用程序，它拥有返回集合的公共API /users 、/photos。注意到它们都是复数名词了吗? 它们也是自描述的，我们可以推断出 /users 和/photos分别是获取产品注册的用户信息和分享的照片。用HTTP方法来描述资源的功能所有资源都有一组方法，可以对它们进行操作由该接口暴露的数据。REStful APIs包含主要的HTTP方法，其良好的定义和独立的功能能够应对所有资源。这里是RESTful API里常用HTTP方法列表，这些方法定义CRUD如何操作资源和集合。(如果你想了解PUT和PATCH的不同，/questionswhat-is-the-main-difference-between-patch-and-put-request?answertab=oldest可以到StackOverflow上看看这个)虽然在URL中使用动词也不错，但是GET, PUT, POST, DELETE操作已经用于描述了资源的操作，因此在URL中使用动词代替名词会显得比较混乱。在照片分享app中，/users 和/photos 是一个端点，API的终端消费者可以更直观的使用RESTful CRUD 进行上述的操作。响应提供反馈,以帮助开发人员成功在他们使用你的产品时向开发人员提供良好的反馈，对于提升使用率和用户维持率是很好的。每一个客户端的请求和服务端的响应都可以看做是一个消息，在理想化的RESTful 生态系统中，这些消息必须是自描述的。良好的反馈对于实现的验证是积极的，错误实现产生的消息可以帮助用户调试和纠正使用产品的不正确方式。对于API, 错误信息是