RESTful API设计手册.pdf

1、RESTful APIg41EEg41D1g187Bg7BC g2D1Eg2CB4 本文档的目的：保证设计的质量，提高工作的效率。当效率跟质量相冲突时，以保证质量为第一要务。RESTful风格的设计是面向资源的设计，所有操作都是针对资源的操作，所以，设计工作：首先是识别资源，并为资源命名（即设计URI）其次是考虑对资源的操作接下来设计这些操作的请求及应答表示考虑典型的处理过程及错误情况，设计响应码本规范涉及四个部分：URI、操作、响应码、请求及应答。URIg41EEg41D1 1. URI中要体现API的版本。每个独立维护的模块都可以有自己的版本号。如果两个模块没有联系，则版本号要分开：正例：

2、/api/module1/v1/.，/api/module2/v1/.反例：/api/v1/module1/.，/api/v1/module2/.2. URI应该是名词性的，而不是动词性的。如，查询合同列表：正例：/contracts反例：/getcontracts说明：URI（统一资源标识）指向的是资源，不能用动词来表示。如果想用动作（如“查询合同”）来表示，那就要从该动作的结果（如“符合查询条件的合同列表”）来考虑一下。3. 用复数形式的词来表示某类资源的列表。如，合同列表：正例：/contracts反例：/contract4. 单个资源的URI用资源列表的URI加“/”，再加该资源的唯一

3、标识（一般是数据库中的主键）来表示。如，某一合同：正例：/contracts/255，其中255是这个合同的ID5. 有层次结构的资源，用“/”来分隔。如，合同的附件列表，附件是属于某一合同的，所以如下表示：正例：/contracts/255/attachments，表示ID为255的合同的所有附件说明：单个合同附件的URI如前所述，用/contracts/255/attachments/20表示ID为255的合同下ID为20的一个附件6. 为特别的目的可专门定义一个资源URI。如，需要一个所有合同的附件列表：正例：/contractsAttachments7. 算法服务也可以定义为一种资源，

4、用算法的结果来表示。如，比较两个文件的差异：正例：/dierence/le1;le2反例：/compare/le1;le28. 涉及多个资源的功能服务也可以定义为一种资源，如转账，涉及转出和转入两个账户资源：正例：/transfer，表示转账交易这种资源，每一次转账，就是创建一个新的转账交易。9. 对于资源列表的URI，可根据需要添加查询参数：/contracts?creator=xxx，表示查询由xxx创建的合同分页查询参数：start：从第几条记录开始返回count：返回的记录条数时间范围参数：starttime：开始时间endtime：结束时间排序参数：sortby：排序依据order：

5、asc-升序，desc-降序10. URI中，非层次关系的结构不要使用“/”分隔。如，指向地图上一个经纬度坐标点的URI：正例：/map/36.5,117.2，表示坐标为北纬36.5东经117.2的一个坐标点反例：/map/36.5/117.2，因为经度不是纬度下面的资源，两个属性是并列的，所以不要用“/”11. URI中，非层次关系的结构，若有前后次序关系，则用逗号分隔；若无次序关系，则用分号分隔。正例：经纬度坐标之间用逗号，前面是纬度，后面是经度，/map/36.5,117.2跟/map/117.2,36.5会指向不同的资源。正例：要取得两种颜色混合后的颜色值，颜色之间用分号，/mixed

6、Color/red;green跟/mixedColor/green;red指向的是同一个资源，都是黄色。如，比较两个文件的差异，/dierence/le1;le2跟/dierence/le2;le1指向的是同一个资源。有人认为它们返回的结果并不一样，就象用linux下的di命令，但我们可以认为这是同一资源的两种不同表示形式，表示的实质内容是同一个，都是这两个文件的差异。如果认为形式不同也算两个资源，那就用逗号进行分隔：/dierence/le1,le2和/dierence/le2,le1表示不同的资源。12. 资源是根据需要提供的服务来确定的，依据系统中的实体对象（数据集）来识别资源只是方法之

7、一。对于系统中的同一实体对象，根据服务需要，可以识别出若干资源。如，对于学生这个实体，需要的资源可能有：/students，表示学生信息列表/studentNames，表示学生姓名列表/studentBriefs，表示学生简要信息列表g1AFDg58Cg41EEg41D1 1. 操作主要使用HTTP的GET、POST、PUT、DELETE。系统实现时，要保证GET操作是安全且幂等的，保证PUT、DELETE操作是幂等的。说明：安全的是指该操作不对资源造成任何修改；幂等的是指该操作调用多次跟调用一次，对资源造成的修改是一样的；要保证幂等时，不能允许客户端对资源的状态作相对改动，比如，将资源的某计

8、数进行加1。2. 对于只读类的操作，统一使用HTTP的GET操作。示例：获取合同列表正例：GET /contracts反例：POST /contracts示例：查询符合某些条件的合同正例：GET /contracts?creator=xxx&status=completed&start=51&count=10反例：POST /contracts，用POST提交查询参数示例：获取ID为255的那个合同的详细信息正例：GET /contracts/2553. 对于创建资源的操作，如果被创建资源的URI是由服务方生成的，则使用POST方法，是在被创建资源的父资源（或工厂资源）上使用POST方法。如，

9、新创建一个合同：正例：POST /contracts说明：新的合同创建后，其ID由服务方分配，比如分配为300，则新创建的合同URI为/contracts/300；POST操作不是幂等的，用相同的参数再调用一次POST /contracts，会创建一个ID为301的新合同。4. 对于创建资源的操作，如果被创建资源的URI不是由服务方生成，而是客户方指定或其它方式确定的，则使用PUT方法，是在该资源的URI上使用PUT方法。如，合同下有一个附件资源，叫合同正本，其URI是/contracts/contractsId/original。当我们为ID为300的合同新增合同正本时，应该：正例：PUT

10、/contracts/300/original反例：POST /contracts/300反例：POST /contracts/300/original说明：因为在该资源创建之前，其URI就已经知道了，所以可以直接访问。因为该资源URI已经存在，我们可以把新建也认为是对该资源的一种修改。PUT方法是幂等的，无论调用多少次，该合同都只会有一个正本附件，所以客户端在不确定调用是否成功的时候，也可以大胆地再次调用。5. 对资源的修改操作，使用PUT方法，是在资源的URI上使用PUT方法。如，修改一个合同的信息：正例：PUT /contracts/3006. 对资源的删除操作，使用DELETE方法，是

11、在资源的URI上使用DELETE方法。如，删除一个合同：正例：DELETE /contracts/3007. 如果确实无法遵循前面的约定，也可以重载POST方法来定义接口操作，即POST并不表示对某个资源的创建，而是有其它含义，具体含义在请求信息中。gAFDg14C4g2E31g41EEg41D1 1. 响应码应充分使用HTTP的响应代码，这将：方便客户端的判断；有利于浏览器、代理等软件依据HTTP的标准采取合理的处理操作。2. 查询资源列表时：如果参数正确，查询到数据，响应码为200，提供响应实体主体；如果参数正确，没有查询到数据，响应码为200，提供响应实体主体，只不过实体主体中的内容是空

12、的；如果参数不正确，响应码为400（请求无效），响应实体主体中说明无效的原因。3. 查询单个资源时：查询到数据，且访问用户有访问数据的权限，响应码为200，提供响应实体主体；查询到数据，但该用户无访问该数据的权限，响应码为404，不提供响应实体主体；没有查询到数据，响应码为404，不提供响应实体主体。4. 创建资源时：如果参数不正确，响应码为400（请求无效），响应实体主体中说明无效的原因；如果要创建的资源跟已有资源标识冲突，响应码为409（Conict），响应实体主体中说明冲突的原因；如果创建成功，响应码为201，响应实体主体中返回新创建的资源。5. 修改资源时：如果参数不正确，响应码为40

13、0（请求无效），响应实体主体中说明无效的原因；如果修改成功，响应码为204，不提供响应实体主体。6. 删除资源时：如果没有找到要删除的资源，响应码为404，不提供响应实体主体；如果删除成功，响应码为204，不提供响应实体主体。7. 如果客户端发送请求数据格式不对（比如要求JSON格式，实际发送XML格式），响应码为415，不提供响应实体主体。8. 服务器运行出错，如数据丢失、数据错误、软件bug、数据库无法访问、读写文件失败、硬件故障等，响应码为500。响应实体主体中说明错误原因。其实对于500错误，客户端即使知道了原因，也无能为力。g4227g2272g9FAg14C4g3184g41EEg41D1 1. 请求及应答均采用JSON格式。2. 返回错误信息时，结构要一致。3. 请求信息尽量简洁，方便使用。4. 应答信息中要包含资源的完整信息。资源包含哪些信息也是接口设计工作的一部分，对于每一种资源，它所包含的信息是确定的；所以，不能出现：在查询资源列表时，每个资源只有三项内容，而查询单个资源时，却返回五顶内容的情况。