RESTful API设计手册

《RESTful API设计手册》由会员上传分享，免费在线阅读，更多相关内容在应用文档-天天文库。

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

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

5、束时间排序参数：sortby：排序依据order：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会指向不

6、同的资源。正例：要取得两种颜色混合后的颜色值，颜色之间用分号，/mixedColor/red;green跟/mixedColor/green;red指向的是同一个资源，都是黄色。如，比较两个文件的差异，/difference/file1;file2跟/difference/file2;file1指向的是同一个资源。有人认为它们返回的结果并不一样，就象用linux下的diff命令，但我们可以认为这是同一资源的两种不同表示形式，表示的实质内容是同一个，都是这两个文件的差异。如果认为形式不同也算两个资源，那就用逗号进行分隔：/difference/file1,file2和/difference

7、/file2,file1表示不同的资源。12.资源是根据需要提供的服务来确定的，依据系统中的实体对象（数据集）来识别资源只是方法之一。对于系统中的同一实体对象，根据服务需要，可以识别出若干资源。如，对于学生这个实体，需要的资源可能有：/students，表示学生信息列表/studentNames，表示学生姓名列表/studentBriefs，表示学生简要信息列表操作设计1.操作主要使用HTTP的GET、POST、PUT、DELETE。系统实现时，要保证GET操作是安全且幂等的，保证PUT、DELETE操作是幂等的。说明：安全的是指该操作不对资源造成任何修改；幂等的是