RESTful接口设计---读《RESTful Web Services Cookbook》笔记

前言

最近需要设计大量RESTful的接口，之前对RESTful只是了解，没系统学习过ta的设计方法。借到一本《RESTful Web Services Cookbook》，也算是RESTful接口设计的经典著作了，书挺厚，本文记录下我认为重要的、易忘的知识点，以备日后查找。

第一章-笔记

如何使用POST/PUT/DELETE方法实现异步操作？

在不考虑各种条件请求前提下，使用RESTful的接口做同步操作很简单，GET成功就返回200（OK），POST成功就返回201（Created），PUT成功可以返回200，也可以返回204（No Content），DELETE成功可以直接204。

但对于异步操作，流程就改变了，这里以POST方法实现异步创建一个book对象为例介绍RESTful做异步操作的大概流程。

1. 首先client向server请求创建一个book，发送 POST http://domain.com/books；
   
2. server在接收该请求并进行简单处理（如生成新book的id等）后立刻返回202（Accepted），表示server已经开始处理异步创建book对象的任务，同时在返回的header中包含Content-Location: http://domain.com/books/1/processtatus，向client暴露查看id=1的book的异步处理状态信息；
3. client基于第2步中返回的Content-Location属性，向server请求Get http://domain.com/books/1/processstatus；
4. server在接收请求并获取process status后返回200，http消息正文包含状态信息；
5. client不断的重复第3步，当server已经完成book的创建后，会返回303（See Other），并且header中加入Location:http://domain.com/boos/1，向client暴露新创建的book的资源URL；

至此整个异步操作结束，这种实现方式得熟悉202和303的使用场景。（参考原书中第1.10～1.11小节）

第五章-笔记

如何使用RESTful接口来实现工作流处理？

在非RESTful协议的系统中，工作流的详细步骤大多是在配置文件定义好的；而在RESTful的系统中，可以认为工作流的每一步也都是一种资源，client通过访问工作流步骤资源来完成整个流程。 中文版《RESTful Web Services Cookbook》在本节写道：“超媒体和链接的主要应用之一就是将客户端从学习服务器用来管理应用程序流程的规则中解耦出来。服务器可以提供包含应用程序状态的链接，从而利用超媒体作为应用程序状态的引擎。”（这翻译。。。）

这里我照搬书中的例子，介绍如何使用RESTful接口来完成招聘员工的整个流程。

方法	URI	目的
POST	http://www.example.org/hires	创建一个应聘者资源
POST	http://www.example.org/hires/{id}/refs	提交介绍人意见
POST	http://www.example.org/hires/{id}/bgchecks	提交背景审查结果
POST	http://www.example.org/hires/{id}/hire	发录用通知
POST	http://www.example.org/hires/{id}/no-hire	不录用

其实大致的路程就是：在创建一个应聘者资源完成后，在返回的数据中均包含了下一步工作步骤的URI，这样就告诉client接下来应该做什么。

【但书中并没有介绍 如何防止client不按照link来完成工作流，比如client完成了“提交介绍人意见”，此时server返回的link是指向“提交背景审查结果”的；但client可以通过一些手段直接去访问“发录用通知”的URI】

我想到的办法，是server端返回的link包含有一个唯一的tag，此tag在server端存储，client提交时server会验证此tag是否是合法的，既能保证请求的合法性，又能强制限制工作流的流程。（在URI上加tag在书中第10章也提到了，以此实现了POST的条件化请求）

<未完待续>