前言:

基于一些不错的RESTful开发组件,可以快速的开发出不错的RESTful API,但如果不了解开发规范的、健壮的RESTful API的基本面,即便优秀的RESTful开发组件摆在面前,也无法很好的理解和使用。下文结合自己的实践经验,整理了从零开始开发RESTful API的核心要点,完善的RESTful开发组件基本都会包含全部或大部分要点,对于支持不够到位的要点,我们也可以自己写代码实现。

1. Request 和 Response

RESTful API的开发和使用,无非是客户端向服务器发请求(request),以及服务器对客户端请求的响应(response)。本真RESTful架构风格具有统一接口的特点,即,使用不同的http方法表达不同的行为:

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

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

  • GET, PUTPATCH请求成功时,要返回对应的数据,及状态码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以规范统一的格式作为数据的载体,常用的格式为jsonxml,以json格式为例,当客户端向服务器发请求时,或者服务器响应客户端的请求,向客户端返回数据时,都是传输json格式的文本,而在服务器内部,数据处理时基本不用json格式的字符串,而是native类型的数据,最典型的如类的实例,即对象(object),json仅为服务器和客户端通信时,在网络上传输的数据的格式,服务器和客户端内部,均存在将json转为native类型数据和将native类型数据转为json的需求,其中,将native类型数据转为json即为序列化,将json转为native类型数据即为反序列化。虽然某些开发语言,如Python,其原生数据类型listdict能轻易实现序列化和反序列化,但对于复杂的API,内部实现时总会以对象作为数据的载体,因此,确保序列化和反序列化方法的实现,是开发RESTful API最重要的一步准备工作

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

3. Validation

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

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

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

4. Authentication 和 Permission

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

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

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

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

全局型的权限机制容易理解,实现也简单,有很多开源库可做备选方案,不少完善的web开发框架,也会集成相关的权限逻辑,object permission 相对难复杂一点,但也有很多典型的应用场景,如多人博客系统中,作者对自己文章的编辑权限即为object permission,其对应的开源库也有很多。开发一套完整的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版本控制允许更改不同客户端之间的行为。 REST框架提供了许多不同的版本控制方案。版本控制由客户的需求所决定,并且可以基于请求URL或基于请求头。有许多有效的方法来接近版本控制。 非版本化系统也可能是适当的,特别是如果你工程化的非常长期的系统,多个客户端在您的控制之外。规范的API应该包含版本信息,

您的域名共享必须包含与具有“version”关键字参数的版本匹配的模式,以便此信息可用于版本控制。实例如下:

urlpatterns = [
url(
r'^(?P<version>(v1|v2))/bookings/$',
bookings_list,
name='bookings-list'
),
url(
r'^(?P<version>(v1|v2))/bookings/(?P<pk>[0-9]+)/$',
bookings_detail,
name='bookings-detail'
)
]

另一种优雅的做法是,使用HTTP header中的accept来传递版本信息,这也是GitHub API 采取的策略

6.2 Use nouns, not verbs

RESTful API 中的url是指向资源的,而不是描述行为的,因此设计API时,应使用名词而非动词来描述语义,否则会引起混淆和语义不清。即:

# Bad APIs
/api/getBook/1/
/api/updateBook1/
/api/deleteBook/1/

上面四个url都是指向同一个资源的,虽然一个资源允许多个url指向它,但不同的url应该表达不同的语义,上面的API可以优化为

# Good APIs
/api/Book/1/

Book资源的获取、更新和删除分别通过 GETPUT 和 DELETE方法请求API即可。试想,如果url以动词来描述,用PUT方法请求 /api/deleteBook/1/ 会感觉多么不舒服。

6.3 GET and HEAD should always be safe

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

# The following api is used to delete articles
# [GET]
/api/deleteBook?id=1

试想,如果搜索引擎访问了上面url会如何?

6.4 Nested resources routing

如果要获取一个资源子集,采用 nested routing 是一个优雅的方式,如,列出所有文章中属于Jason编写的文章:

# List Gevin's articles
/api/authors/Jason/articles/

获取资源子集的另一种方式是基于filter(见下面章节),这两种方式都符合规范,但语义不同:如果语义上将资源子集看作一个独立的资源集合,则使用 nested routing 感觉更恰当,如果资源子集的获取是出于过滤的目的,则使用filter更恰当。

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

6.5 Filter

对于资源集合,可以通过url参数对资源进行过滤,如:

# List Gevin's articles
/api/articles?author=Jason

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

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 库,虽然其相关接口基本涵盖了本文的全部或大部分内容,但本文的总结,相信对这些库的理解和使用也是有帮助的。

 

Django REST Framework 学习笔记的更多相关文章

  1. Django RF:学习笔记(8)——快速开始

    Django RF:学习笔记(8)——快速开始 安装配置 1.使用Pip安装Django REST Framework: pip install djangorestframework 2.在Sett ...

  2. Entity Framework 学习笔记(2)

    上期回顾:Entity Framework 学习笔记(1) Entity Framework最主要的东西,就是自己创建的.继承于DbContext的类: /// <summary> /// ...

  3. Entity Framework学习笔记

    原文地址:http://www.cnblogs.com/frankofgdc/p/3600090.html Entity Framework学习笔记——错误汇总   之前的小项目做完了,到了总结经验和 ...

  4. ADO.NET Entity Framework学习笔记(3)ObjectContext

    ADO.NET Entity Framework学习笔记(3)ObjectContext对象[转]   说明 ObjectContext提供了管理数据的功能 Context操作数据 AddObject ...

  5. Spring Framework 学习笔记——核心技术之Spring IOC

    Spring Framework 官网文档学习笔记--核心技术之Spring IOC 官方文档 spring-framework-5.3.9 1. Spring Framework 核心技术 1.1 ...

  6. Entity Framework学习笔记——错误汇总

    之前的小项目做完了,到了总结经验和更新学习笔记的时间了.开始正题之前先啰嗦一下,对之前的学习目标进行一个调整:“根据代码生成表”与“生成数据库脚本和变更脚本”合并为“Code First模式日常使用篇 ...

  7. Django REST Framework学习——Android使用REST方法访问Diango

    本文更应该叫做Android如何模拟浏览器访问Django服务器后台. 环境为: Android通过HttpClient访问服务器,从Django中获取json数据,解析显示在UI界面上. 问题为: ...

  8. 完整的Django入门指南学习笔记1

    转自[https://blog.csdn.net/qq_35554125/article/details/79462885] part 1: 前沿 教程材料一共会被分为七个部分. 此教程将从安装.开发 ...

  9. robot framework学习笔记2

    声明:本笔记都只是自己根据大牛虫师的robot系列文档学习记录的,学习的话还请移步虫师博客:https://www.cnblogs.com/fnng/ 非常感谢大牛的分享,带小白一步一步入门   F5 ...

随机推荐

  1. 通过代码注册COM、DLL组件

    注册代码如下:  C++ Code  1234567891011121314151617181920212223242526272829303132333435363738   // //====== ...

  2. localStorage变更事件当前页响应新解-awen

    html5的localStorage相信大家都是很熟悉了,但是在chrome等支持该对象的浏览器中(ie10除外),如果你监听storage变更事件你就会发现,当数据发生变化时本页是监听不到stora ...

  3. Angular 表单(二) - 模板驱动表单

    import { Component, OnInit } from '@angular/core'; import { Hero} from '../hero'; @Component({ selec ...

  4. DecimalFormat 四舍五入Float类型的坑

    今天又踩了一个坑,使用DecimalFormat来完毕四舍五入.可是传入的是float类型,几轮測试才发现一个问题,传入的float会被转为double类型.大家都知道float是4位,double是 ...

  5. keyword static

    1. 不能通过类名来调用类的非静态成员函数 2. 类的对象可以使用静态成员函数和非静态成员函数 3. 静态成员函数中不能引用非静态成员 因为静态成员函数属于整个类, 在类的实例化对象之前就已经分配了空 ...

  6. js让程序暂停运行的方法

    //自己写的暂停毫秒数的函数 function pauseTime(millTime) { var start=Date.now(); while(true){ var nowTime=Date.no ...

  7. deviceready has not fired after 5 seconds

    deviceready has not fired after 5 seconds 建议用手机连上电脑,用真机进行调试:

  8. 常用 Git 操作

    最新博客链接:https://feiffy.cc/Git 日常用到的GIT的一些操作,记下来,以备参考. 删除文件 git rm filename git commit -m "remove ...

  9. php 验证上传图片尺寸

    getimagesize 函数 取得图像大小 (PHP 4, PHP 5) array getimagesize ( string filename [, array &imageinfo] ...

  10. 剑指Offer——二叉树的深度

    题目描述: 输入一棵二叉树,求该树的深度.从根结点到叶结点依次经过的结点(含根.叶结点)形成树的一条路径,最长路径的长度为树的深度. 分析: 二叉树的深度等于其左子树的深度和右子树的深度两个中最大的深 ...