RESTful API 编写指南

本文首发于Gevin的博客

原文连接：RESTful API 编写指南

未经 Gevin 受权，禁止转载

---

基于一些不错的RESTful开发组件，能够快速的开发出不错的RESTful API，但若是不了解开发规范的、健壮的RESTful API的基本面，即使优秀的RESTful开发组件摆在面前，也没法很好的理解和使用。下文Gevin结合本身的实践经验，整理了从零开始开发RESTful API的核心要点，完善的RESTful开发组件基本都会包含所有或大部分要点，对于支持不够到位的要点，咱们也能够本身写代码实现。

Outline

• Request 和 Response
• Serialization 和 Deserialization
• Validation
• Authentication 和 Permission
• CORS
• URL Rules

1. Request 和 Response

RESTful API的开发和使用，无非是客户端向服务器发请求（request），以及服务器对客户端请求的响应（response）。本真RESTful架构风格具备统一接口的特色，即，使用不一样的http方法表达不一样的行为：

• GET（SELECT）：从服务器取出资源（一项或多项）
• POST（CREATE）：在服务器新建一个资源
• PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）
• PATCH（UPDATE）：在服务器更新资源（客户端提供须要修改的资源数据）
• DELETE（DELETE）：从服务器删除资源

客户端会基于GET方法向服务器发送获取数据的请求，基于PUT或PATCH方法向服务器发送更新数据的请求等，服务端在设计API时，也要按照相应规范来处理对应的请求，这点如今应该已经成为全部RESTful API的开发者的共识了，并且各web框架的request类和response类都很强大，具备合理的默认设置和灵活的定制性，Gevin在这里仅准备强调一下响应这些request时，经常使用的Response要包含的数据和状态码（status code），不完善的内容，欢迎你们补充:

• 当GET, PUT和PATCH请求成功时，要返回对应的数据，及状态码200，即SUCCESS
• 当POST建立数据成功时，要返回建立的数据，及状态码201，即CREATED
• 当DELETE删除数据成功时，不返回数据，状态码要返回204，即NO CONTENT
• 当GET 不到数据时，状态码要返回404，即NOT FOUND
• 任什么时候候，若是请求有问题，如校验请求数据时发现错误，要返回状态码 400，即BAD REQUEST
• 当API 请求须要用户认证时，若是request中的认证信息不正确，要返回状态码 401，即NOT AUTHORIZED
• 当API 请求须要验证用户权限时，若是当前用户无相应权限，要返回状态码 403，即FORBIDDEN

最后，关于Request 和 Response，不要忽略了http header中的Content-Type。以json为例，若是API要求客户端发送request时要传入json数据，则服务器端仅作好json数据的获取和解析便可，但若是服务端支持多种类型数据的传入，如同时支持json和form-data，则要根据客户端发送请求时header中的Content-Type，对不一样类型是数据分别实现获取和解析；若是API响应客户端请求后，须要返回json数据，须要在header中添加Content-Type=application/json。

2. Serialization 和 Deserialization

Serialization 和 Deserialization即序列化和反序列化。RESTful API以规范统一的格式做为数据的载体，经常使用的格式为json或xml，以json格式为例，当客户端向服务器发请求时，或者服务器相应客户端的请求，向客户端返回数据时，都是传输json格式的文本，而在服务器内部，数据处理时基本不用json格式的字符串，而是native类型的数据，最典型的如类的实例，即对象（object），json仅为服务器和客户端通讯时，在网络上传输的数据的格式，服务器和客户端内部，均存在将json转为native类型数据和将native类型数据转为json的需求，其中，将native类型数据转为json即为序列化，将json转为native类型数据即为反序列化。虽然某些开发语言，如Python，其原生数据类型list和dict能轻易实现序列化和反序列化，但对于复杂的API，内部实现时总会以对象做为数据的载体，所以，确保序列化和反序列化方法的实现，是开发RESTful API最重要的一步准备工做

题外话，序列化和反序列化的便捷，造就了RESTful API跨平台的特色，使得REST取代RPC成为Web Service的主流

序列化和反序列化是RESTful API开发中的一项硬需求，因此几乎每一种经常使用的开发语言都会有一个或多个优秀的开源库，来实现序列化和反序列化，所以，咱们在开发RESTful API时，不必制造重复的轮子，选一个好用的库便可，如python中的marshmallow，若是基于Django开发，Django REST Framework中的serializer便可。

3. Validation

Validation即数据校验，是开发健壮RESTful API中另外一个重要的一环。仍以json为例，当客户端向服务器发出post, put或patch请求时，一般会同时给服务器发送json格式的相关数据，服务器在作数据处理以前，先作数据校验，是最合理和安全的先后端交互。若是客户端发送的数据不正确或不合理，服务器端通过校验后直接向客户端返回400错误及相应的数据错误信息便可。常见的数据校验包括：

• 数据类型校验，如字段类型若是是int，那么给字段赋字符串的值则报错
• 数据格式校验，如邮箱或密码，其赋值必须知足相应的正则表达式，才是正确的输入数据
• 数据逻辑校验，如数据包含出生日期和年龄两个字段，若是这两个字段的数据不一致，则数据校验失败

以上三种类型的校验，数据逻辑校验最为复杂，一般涉及到多个字段的配合，或者要结合用户和权限作相应的校验。Validation虽然是RESTful API 编写中的一个可选项，但它对API的安全、服务器的开销和交互的友好性而言，都具备重要意义，所以，Gevin建议，开发一套完善的RESTful API时，Validation的实现必不可少。

4. Authentication 和 Permission

Authentication指用户认证，Permission指权限机制，这两点是使RESTful API 强大、灵活和安全的基本保障。

经常使用的认证机制是Basic Auth和OAuth，RESTful API 开发中，除非API很是简单，且没有潜在的安全性问题，不然，认证机制是必须实现的，并应用到API中去。Basic Auth很是简单，不少框架都集成了Basic Auth的实现，本身写一个也能很快搞定，OAuth目前已经成为企业级服务的标配，其相关的开源实现方案很是丰富（更多）。

我在《RESTful 架构风格概述》中，对认证机制作了更加详细的描述，有兴趣的同窗不妨阅读相关章节。

权限机制是对API请求更近一步的限制，只有经过认证的用户符合权限要求，才能访问API。权限机制的具体实现一般依赖于系统的业务逻辑和应用场景，generally speaking，经常使用的权限机制主要包含全局型的和对象型的，全局型的权限机制，主要指经过为用户赋予权限，或者为用户赋予角色或划分到用户组，而后为角色或用户组赋予权限的方式来实现权限控制，对象型的权限机制，主要指权限控制的颗粒度在object上，用户对某个具体对象的访问、修改、删除或其行为，要单独在该对象上为用户赋予相关权限来实现权限控制。

全局型的权限机制容易理解，实现也简单，有不少开源库可作备选方案，很多完善的web开发框架，也会集成相关的权限逻辑，object permission 相对难复杂一点，但也有不少典型的应用场景，如多人博客系统中，做者对本身文章的编辑权限即为object permission，其对应的开源库也有不少。

注： 我写过一篇《Django权限机制的实现》，Django 开发者可作延伸阅读。

开发一套完整的RESTful API，权限机制必须归入考虑范围，虽然权限机制的具体实现依赖于业务，权限机制自己，是有典型的模式存在的，须要开发者掌握基本的权限机制实现方案，以便随时应用到API中去。

5. CORS

CORS即Cross-origin resource sharing，在RESTful API开发中，主要是为js服务的，解决javascript 调用 RESTful API时的跨域问题。

因为固有的安全机制，js的跨域请求时是没法被服务器成功响应的。如今先后端分离日益成为web开发主流方式的大趋势下，后台逐渐趋向指提供API服务，为各客户端提供数据及相关操做，而网站的开发所有交给前端搞定，网站和API服务不多部署在同一台服务器上并使用相同的端口，js的跨域请求时广泛存在的，开发RESTful API时，一般都要考虑到CORS功能的实现，以便js能正常使用API。

目前各主流web开发语言都有不少优秀的实现CORS的开源库，咱们在开发RESTful API时，要注意CORS功能的实现，直接拿现有的轮子来用便可。

更多关于CORS的介绍，有兴趣的同窗能够查看阮一峰老师的跨域资源共享 CORS 详解

6. URL Rules

RESTful API 是写给开发者来消费的，其命名和结构须要有意义。所以，在设计和编写URL时，要符合一些规范。Url rules 能够单独写一篇博客来详细阐述，本文只列出一些关键点。

6.1 Version your API

规范的API应该包含版本信息，在RESTful API中，最简单的包含版本的方法是将版本信息放到url中，如：

/api/v1/posts/
/api/v1/drafts/

/api/v2/posts/
/api/v2/drafts/复制代码

另外一种优雅的作法是，使用HTTP header中的accept来传递版本信息，这也是GitHub API 采起的策略。

6.2 Use nouns, not verbs

RESTful API 中的url是指向资源的，而不是描述行为的，所以设计API时，应使用名词而非动词来描述语义，不然会引发混淆和语义不清。即：

# Bad APIs
/api/getArticle/1/
/api/updateArticle/1/
/api/deleteArticle/1/复制代码

上面四个url都是指向同一个资源的，虽然一个资源容许多个url指向它，但不一样的url应该表达不一样的语义，上面的API能够优化为：

# Good APIs
/api/Article/1/复制代码

article 资源的获取、更新和删除分别经过 GET, PUT 和 DELETE方法请求API便可。试想，若是url以动词来描述，用PUT方法请求 /api/deleteArticle/1/ 会感受多么不舒服。

6.3 GET and HEAD should always be safe

RFC2616已经明确指出，GET和HEAD方法必须始终是安全的。例如，有这样一个不规范的API:

# The following api is used to delete articles
# [GET]
/api/deleteArticle?id=1复制代码

试想，若是搜索引擎访问了上面url会如何？

6.4 Nested resources routing

若是要获取一个资源子集，采用 nested routing 是一个优雅的方式，如，列出全部文章中属于Gevin编写的文章：

# List Gevin's articles
/api/authors/gevin/articles/复制代码

获取资源子集的另外一种方式是基于filter（见下面章节），这两种方式都符合规范，但语义不一样：若是语义上将资源子集看做一个独立的资源集合，则使用 nested routing 感受更恰当，若是资源子集的获取是出于过滤的目的，则使用filter更恰当。

至于编写RESTful API时到底应采用哪一种方式，则仁者见仁，智者见智，语义上说的通便可。

6.5 Filter

对于资源集合，能够经过url参数对资源进行过滤，如：

# List Gevin's articles
/api/articles?author=gevin复制代码

分页就是一种最典型的资源过滤。

6.6 Pagination

对于资源集合，分页获取是一种比较合理的方式。若是基于开发框架（如Django REST Framework），直接使用开发框架中的分页机制便可，若是是本身实现分页机制，Gevin的策略是：

返回资源集合是，包含与分页有关的数据以下：

{
  "page": 1,            # 当前是第几页
  "pages": 3,           # 总共多少页
  "per_page": 10,       # 每页多少数据
  "has_next": true,     # 是否有下一页数据
  "has_prev": false,    # 是否有前一页数据
  "total": 27           # 总共多少数据
}复制代码

当想API请求资源集合时，可选的分页参数为：

参数	含义
page	当前是第几页，默认为1
per_page	每页多少条记录，默认为系统默认值

另外，系统内还设置一个per_page_max字段，用于标记系统容许的每页最大记录数，当per_page值大于 per_page_max 值时，每页记录条数为 per_page_max。

6.7 Url design tricks

（1）Url是区分大小写的，这点常常被忽略，即：

• /Posts
• /posts

上面这两个url是不一样的两个url，能够指向不一样的资源

（2）Back forward Slash (/)

目前比较流行的API设计方案，一般建议url以/做为结尾，若是API GET请求中，url不以/结尾，则重定向到以/结尾的API上去（这点如今的web框架基本都支持），由于有没有 /，也是两个url，即：

• /posts/
• /posts

这也是两个不一样的url，能够对应不一样的行为和资源

（3）链接符 - 和 下划线 _

RESTful API 应具有良好的可读性，当url中某一个片断（segment）由多个单词组成时，建议使用 - 来隔断单词，而不是使用 _，即：

# Good
/api/featured-post/

# Bad
/api/featured_post/复制代码

这主要是由于，浏览器中超连接显示的默认效果是，文字并附带下划线，若是API以_隔断单词，两者会重叠，影响可读性。

总结

编写本文的初衷，是为了整理一套从零开始编写规范、安全的RESTful API的基本思路。本文介绍了开发RESTful API时，要考虑的基本内容，对于相似Flask这种天生支持RESTful风格的web框架，不依赖其余RESTful第三方库开发RESTful 服务时，能够从本文内容入手；很多强大的RESTful 库，虽然其相关接口基本涵盖了本文的所有或大部份内容，但本文的总结，相信对这些库的理解和使用也是有帮助的。

最后，关于如何开发RESTful API，欢迎你们与我交流~