REST API 设计与开发最佳实践

21CTO社区导读：在本文中，我的目标是向大家尽可能详细的解释REST API，包括理论和开发部分。以便大家能清楚的了解何时用以及如何使用它，包括它的本质是什么。无论是自己开发API还是使用第三方API，都会更加顺利。

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

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

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

REST与HTTP有什么区别？

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

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

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

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

REST的本质

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

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

REST绑定HTTP

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

RESTful API的含义

RESTful有下列一些特点：

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

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

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

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

为什么需要用 Restful API

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

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

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

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

我们知道了重点，让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开发的另一个重要方面。有好几个很好的方法来处理错误。

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

Twitter:

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

响应：状态码 400

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

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

Facebook：

请求：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给够给你一个更具体的错误信息。

Twilio：

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

响应：状态码 404

20404

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

https://www.twilio.com/docs/errors/20404

404

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的无状态特性，在实现它们时请务必小心谨慎。 比如最后一个请求的状态未返回， 客户端应该存储和验证状态。

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