REST API 设计与开发实践_rest api 设计 需要code 返回代码吗

像Alibaba,Baidu,Tecent,Toutiao，Facebook,Google,Amazon等公司都拥有开放的RESTful API或开放，我们可以申请访问，获取甚至写入数据。

所有的事情都要问为什么。为什么需要REST API ？REST为何如此普及？

当然，传递信息有很多种方式。如Socket，REST，WebService，HTTP等。

REST很灵活，与HTTP协议兼容。它是一个架构风格，并非标准，用它来提供各种服务，可以用各种编程语言来实现。

在本篇文章中，我们的目标是一起清晰的了解 REST，知道何时用以及如何使用它，以及REST的本质。

我们将通过一些基础知识和定义，包括REST API的最佳实践，可以让各位能够用任何开发语言来实现REST API。

建议您有HTTP协议基础，或者了解一部分，可以充分消化这部分内容。

REST - Representational State Transfer是Roy Field博士创立的一种架构风格，他在UC Irvine的论文中描述了架构风格与基于Web的软件架构设计，并使用HTTP 1.1开发。

我们使用REST做为互联网上不同计算机系统间通信的一种方式。

REST绑定HTTP

根据REST定义，并非如此。尽管人们可以使用其它一些REST应用程序协议，但在涉及REST实现时，HTTP仍然是应用程序协议中无可争辩的主流。

RESTful有下列一些特点：

1、客户端/服务器架构：完整的服务由前端“客户端”和整个系统的后端“服务器”组成。

2、无状态：服务器在不同请求中间不保存任何状态。会话的状态完全由客户端负责。根据REST的定义：所有REST交互都是无状态的，也就是说，每个请求都包含连接器理解请求所需的全部信息，而不受任何先前可能发生的请求影响。

3、可缓存：客户端应该能够将响应存储在缓存中，以便获得更好的性能。

RESTful API遵循以上这些规则，并使用HTTP方法来操作资源集的服务。

因为它们提供了一种简单、灵活和可扩展的方式来开发Web通信的分布式应用程序。

我们可能有很多REST API。如果业务足够广，需要开放的服务也会变得复杂。

开发者需要一些实用主义才能做出好的应用和服务。

理论对于认知理解很重要，但理论的实施才是区分优劣应用差异的检验标准。为此，我们要聪明的工作，但一定要记得，最终用户才是第一优先级，是最高价值。

我们知道了重点，让API做得强大易，让用户的工作也变得更容易 。

在开发软件时，我们会经常使用面向对象的抽象和多态来开发应用程序。这样可以最大化重用代码。

那么，我们是不是也应该这样开发REST API？

到开发API的情况就不同了，对于REST API，具体比抽象更好。也就是完成实际的功能更好。我们来看一些实例：

有两个api版本：

/entities

/entitie

/owners

/blogs

/blogposts

您做为开发者，哪个描述会更清楚，您愿意用哪个API？我选择第二个。

URI格式，使用名词而非动词

下面是API开发的另一个最佳实践。我们如何格式化你的结点？如果你使用编码的方法来命名URI结点，会是以下的结果：

/getAllBlogPosts

/updateBlogPost/12

/deleteBlogPost/12

/updateAuthor/3

/deleteAuthor/3

我想您已经明白，这会有很多个URL结点，每个结点只做一件事情。

我们要有一个更系统的命名来精简梳理上面这个摊子。先把资源用名词来描述，把HTTP方法换成动词。于是我们会得到下面这样的结果：

GET /blogpsots - 取得所有的博客

GET /blogposts/12 - 取得ID为12的博客

POST /blogposts - 添加一个新的博客，返回错误信息

DELETE /blogposts/12 - 删除ID为12的博客

GET /author/3/blogposts - 获取ID为3的作者全部博客

这样，一个更简洁，精确的API 就出现了。对于使用的用户来讲，他会马上清楚。当然，你可以使用单数形式而不是复数形式，这样显得资源名称更为整洁，您根据自己的喜好，这点取决于自己。

本阶段是API开发的另一个重要方面。有好几个很好的方法来处理错误。

我们来看一些高级的开发狗是咋干的：

请求：GET https://api.twitter.com/1.1/account/settings.json

响应：状态码 400

{"errors":[{"code":215,"message":"Bad Authentication data."}]}

Twitter给我们的状态码和错误码，以及一个简短说明。

请求：GET https://graph.facebook.com/me/photos

响应：状态码 400

{

"error": {

"message": "An active access token must be used to query information about the current user.",

"type": "OAuthException",

"code": 2500,

"fbtrace_id": "DzkTMkgIA7V"

}

}

Facebook给够给你一个更具体的错误信息。

请求：GET https://api.twilio.com/2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234

响应：状态码 404

<?xml version='1.0' encoding='UTF-8'?>

<TwilioResponse>

<RestException>

<Code>20404</Code>

<Message>The requested resource /2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234 was not found</Message>

<MoreInfo>https://www.twilio.com/docs/errors/20404</MoreInfo>

<Status>404</Status>

</RestException>

</TwilioResponse>

Twilio给我们一个XML响就格式，并且能够链到你能找到错误细节的文档。

我们看到，不同的开发者提供方法存在一些区别。但是这些开放平台都提供了具体的错误信息，不会只简单告诉用户不可用，让用户不知道发生了什么，让他们在搜索引擎无目的的搜索只会浪费时间。

 

在设计REST API时，需要使用HTTP状态代码与API进行通信。

如你所想，HTTP有很多现成状态码，可以描述一些可能的响应。

但是，我们应该用多少？我们应该对每一种情况都有严格的状态编码么？

HTTP状态码超过70个状态，你知道他们的核心吗？ API用户是否会用到它们，避免让大家再去查。我们大多数都熟悉以下的状态码：

200 OK

400 Bad Request

500 Internal Server Error

我们先从这三点开始，来逐步覆盖REST API的大部分功能。

其它常见的状态码：

201 Created

204 No Content

401 Unauthorized

403 Forbidden

404 Not Found

可以通过功能帮助用户快速找出结果。 如果觉得状态代码不够在错误处理显示描述性内容，那么应该包含某类型的消息。 再通过代码和描述性信息来帮助API用户。

REST API安全性依赖于标准的HTTP机制，如基本认证或摘要认证 。

每个请求都应该通过HTTPS进行 。

提高REST API的安全性有很多技巧，但是由于REST的无状态特性，在实现它们时请务必小心谨慎。 比如最后一个请求的状态未返回， 客户端应该存储和验证状态。

另外，使用时间戳和记录请求对我们也有很大帮助。

关于此话题还有很多要说的，但不在本文的讨论范围内。 如果您想了解更多关于HTTP安全的信息，请查阅21CTO公众号或社区网站。

我们已经编写了REST API，许多用户已经用上了它，我们对此感到满意。

但是出现了新功能，需要增加或修改原有功能和方法，有可能还是很大的变化。

不必担心，我们有解决方案。

在开始开发API之前，我们可以通过将API版本前添加到URI端点，以此达到API版本化。如下：

https://api.21cto.com/v1/authors/2/blogposts/13

这样，只要API发生重大变更，就可以随时增加API版本号（比如，v2，v3 ...）。 这也向用户发出信号，说明一些重要的变化，使用新版本时应该小心。

这是一个简而易见的方法。您可能是世界上最好的API开发者，但如若没有文档，API就失去一半的生命力。

正确完整的文档对于每个软件产品和Web服务都至关重要。

当然，您当然可以通过保持一致并使用清晰的描述性语法来让用户很容易的学习。 但是，好的文档仍然不可或缺。

以下是一些开放平台API的文档例子：

https://www.twilio.com/docs/api/rest/

https://developers.facebook.com/docs/

https://developers.google.com/maps/documentation/

有很多工具可以我们开发和调试API，但是不要忘了添加人的测试和理解，让一个人可以正确理解您的思维。

我们在本文了解了构建REST API的概念，并介绍了一些REST API的最佳开发实践。 如果您第一次尝试开发自己的REST API。 可以尝试在本文中的REST API最佳实践。

先从最小的API开始，遵循这几个实践，相信您会成就感满满。

后面我们有一个持续的系列文章，展示相关语言开发实践。 比如您是C#或者Java专家，了解如何以几种不同的方式使用RESTful API 。

免费提供最新Linux技术教程书籍，为开源技术爱好者努力做得更多更好：http://www.linuxprobe.com/