RESTfulAPI设计原则与规范

1、RESTful API 设计原则与规范 一、背景与基础概念2 二、RESTful API 应遵循得原则3 1、协议 (Protocol)3 2、域名(ROOT URL)3 3、版本 (Versioning)3 4、路径 (Endpoints)3 5、HTTP 动词(HTTP Verbs)5 6、过滤信息( Filtering )5 7 、状态码( Status Codes )6 8 、错误处理( Error handling )7 9、返回结果( Response )7 10、使用 HATEOAS 得 Hypermedia API8 11 、认证( Authentication )8 三、Sw

2、agger API 标准9 REST,即卩 Representational State Transfe得缩写。RESTful 架构，就是 目前最流行得一种互联网软件架构。它结构清晰、符合标准、易于理解、 扩展方便，基于这个风格设计得软件可以更简洁，更有层次，更易于实现 缓存等机制，所以正得到越来越多网站得采用。如果一个架构符合 REST 原则，就称它为 RESTful 架构。 本文即将描述得，即就是创建 RESTful 架构得 API 所要遵循得原则与 规范 、背景与基础概念 Web 应用程序最重要得 REST 原则就是，客户端与服务器之间得交互 在请求之间就是无状态得。从客户端到服务器得每

3、个请求都必须包含理解 请求所必需得信息。 ?资源（resource :网络上得一个实体或者说就是一个具体信息，可 以就是一段文本、一张图片、一首歌曲、一种服务。 ? 统一资源定位符（ URI ， Universal Resource Identifier :一个资源得 识别符或者说就是一个地址，通过 URI 您可以定位到特定得资源。要获 取这个资源，需要访问它得 URI ，因此， URI 就成了每一个资源得地址 或独一无二得识别符。 ? 状态转换（ State Transfer : 所有资源都共享统一得接口，以便在客 户端与服务器之间传输状态。客户端与服务器互动得过程，通常涉及到 服务器端数据

4、与状态得变化过程，比如文件被修改，访问数量增加等。 使用得就是标准得 HTTP 方法， Http 标准中定义得最主要四个动词: GET 、 POST、 PUT、 DELETE 。它们分别对应四种基本操作: - GET : 用来获取资源 - POST: 用来新建资源 - PUT : 用来更新资源 - DELETE : 用来删除资源 ? Hypermedia 就是应用程序状态得引擎，资源表示通过超链接互联。 二、 RESTful API 应遵循得原则 1 、协议 (Protocol) API 与用户得通信协议，尽量使用 HTTPs 协议。 HTTPs 协议得所有 信息都就是加密传播，第三方无法窃听

5、，具有校验机制，一旦被篡改，通 信双方会立刻发现，配备身份证书，防止身份被冒充。 2 、域名 (ROOT URL) 应该尽量将 API 部署在专用域名之下。 如果确定 API 很简单，不会有进一步扩展，可以考虑放在主域名下。 3 、版本 (Versioning) 应该将 API 得版本号放入 URL 。 另一种做法就是，将版本号放在 HTTP 头信息中，但不如放入 URL 方便与直观。 Github 采用这种做法。 注：需要注意版本规划，以便以后 API 得升级与维护。使得 API 版本变得强制 性，不要发布无版本得 API，使用简单数字，避免小数点如 2、5o 4 、路径 (Endpoint

6、s) 路径表示API得具体网址URL。在RESTful架构中，每个 URL代表 一种资源(resource，所以网址中不能有动词，只能有名词，而且所用 得名词往往与代表得对象名称对应。一般来说，某一同种记录得”集合” (collection)，所以API中得名词也应该使用复数。 具体细则： 1、使用名词而不就是动词。举例来说，某个URL 就是 /cards/show/1 ，其中 show 就是动词，这个 URL 就设计错了，正确得写法 应该就是/cards/1，然后用GET方法表示show。如果某些动作就是 HTTP 动词表示不了得，您就应该把动作做成一种资源。比如网上汇款， 从账户1向账户2

7、汇款500元，错误得URI就是：POST /accou nts/1/tra nsfer/500/to/2 。正确得写法就是把动词 transfer改成名词 tran sactio n,资源不能就是动词，但就是可以就是一种服务：POST /transaction?from=1&to=2&amount=500 、 00。 2、使用复数名词。不要混淆名词单数与复数，为了保持简单，只对 所有资源使用复数。 举例： /cars 而不就是 /car /users 而不就是 /user /products 而不就是 /product /settings 而不就是 /setting 3、使用子资源表达关系。如

8、果一个资源与另外一个资源有关系，使 用子资源。 举例： GET /cars/911/drivers/ 返回 car 911 得所有司机 GET /cars/911/drivers/8 返回 car 911 得 8 号司机 5 、HTTP 动词 (HTTP Verbs) 对于资源得具体操作类型，由 HTTP 动词表示。常用得 HTTP 动词有 下面五个： ? GET （ SELECT ）：从服务器取出资源（一项或多项）。 ? POST（CREATE ）：在服务器新建一个资源。 ? PUT （UPDATE ）：在服务器更新资源（客户端提供改变后得完整资源）。 ? PATCH （ UPDATE ）：

9、在服务器更新资源（客户端提供改变得属性）。 ? DELETE （ DELETE ）：从服务器删除资源。 还有两个不常用得 HTTP 动词。 ? HEAD ：获取资源得元数据。 ? OPTIONS ：获取信息，关于资源得哪些属性就是客户端可以改变得。 注：Get方法与查询参数不应该涉及状态改变。使用 PUT, POST与DELETE方法 而不就是 GET 方法来改变状态。 6 、过滤信息（ Filtering ） 如果记录数量很多，服务器不可能都将它们返回给用户。 API 应该提 供参数，过滤返回结果。为集合提供过滤、排序、选择与分页等功能。 下面就是一些常见得参数。 ? ?limit=10 ：

10、指定返回记录得数量 ? ?offset=10:指定返回记录得幵始位置。 ? ?pageNumber=2&perSize=100指定第几页，以及每页得记录数。 ? ?sortby=name&order二asc：指定返回结果按照哪个属性排序，以及排序顺序。 ? ?animal_type_id=1：指定筛选条件 参数得设计允许存在冗余，即允许 API 路径与 URL 参数偶尔有重 复。比如， GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 得含义就是 相同得 注： 移动端能够显示其中一些字段，它们其实不需要一个资源得所有字段，给 API 消费者一个选择字段得

11、能力，这会降低网络流量，提高 API 可用性。 为了将总数发给客户端，使用订制得 HTTP 头： X-Total-Count 、 7 、状态码（ Status Codes ） 服务器向用户返回得状态码与提示信息，常见得有以下一些（方括号 中就是该状态码对应得 HTTP 动词）。 ? 200 OK - GET ：服务器成功返回用户请求得数据，该操作就是幂等得 （Idempotent）。 ? 201 CREATED - POST/PUT/PATCH ：用户新建或修改数据成功。 ? 202 Accepted - *：表示一个请求已经进入后台排队（异步任务） ? 204 NO CONTENT - DE

12、LETE ：用户删除数据成功。 ? 400 INVALID REQUEST - POST/PUT/PATCH ：用户发出得请求有错误，服 务器没有进行新建或修改数据得操作，该操作就是幂等得。 ? 401 Unauthorized - *：表示用户没有权限（令牌、用户名、密码错误）。 ? 403 Forbidden - *：表示用户得到授权（与 401错误相对），但就是访问就是 被禁止得。 ? 404 NOT FOUND - * ：用户发出得请求针对得就是不存在得记录，服务器没 有进行操作，该操作就是幂等得 ? 406 Not Acceptable - GET:用户请求得格式不可得(比如用户请求

13、JSON格 式，但就是只有 XML 格式)。 ? 410 Gone -GET:用户请求得资源被永久删除，且不会再得到得。 ? 422 Unprocesable entity - POST/PUT/PATCH :当创建一个对象时，发生一个 验证错误。 ? 500 INTERNAL SERVER ERROR - * :服务器发生错误，用户将无法判断发 出得请求就是否成功。 8 、错误处理( Error handling ) 如果状态码就是4xx，就应该向用户返回出错信息。尽量使用详细得 错误包装信息: errors: userMessage: Sorry, the requested resour

14、ce does not exist, internalMessage: No car found in the database, code: 4xx, more info: 、 example 、 com/api/v1/errors/12345 9 、返回结果( Response ) 服务器返回得数据格式，应该尽量使用JSON，避免使用XML。针对 不同操作，服务器向用户返回得结果应该符合以下规范。 ? GET /collection :返回资源对象得列表(数组) ? GET /collection/resource :返回单个资源对象 ? POST /collection :返回新生成得资

15、源对象 ? PUT /collection/resource ：返回完整得资源对象 ? PATCH /collection/resource ：返回完整得资源对象 ? DELETE /collection/resource ：返回一个空文档 10、使用 HATEOAS 得 Hypermedia API RESTful API 最好使用 Hypermedia as the Engine of Application Stat（e 超 媒体作为应用状态得引擎），即返回结果中提供链接，连向其她 API 方 法，超文本链接可以建立更好得文本浏览，使得用户不查文档，也知道下 一步应该做什么。 比如，当用

16、户向 api、 example、com 得根目录发出请求，会得到这样 一个文档。 link: rel: collection , href: , title: List of zoos, type: application/vnd、 yourformat+json 上面代码表示，文档中有一个 link 属性，用户读取这个属性就知道下 一步该调用什么 API 了。rel表示这个API与当前网址得关系（collection 关系，并给出该 collection得网址），href表示API得路径，title表示API 得标题， type 表示返回类型。 11 、认证（ Authentication

17、） API 得身份认证尽量使用 OAuth 2、0 框架。 三、 Swagger API 标准 API得文档管理与信息描述，将使用 Swagger行。 Swagger就是一个规范与完整得框架，用于生成、描述、调用与可视 化RESTful风格得Web服务。Swagger得目标就是对 REST API定义一个 标准得与语言无关得接口，可让人与计算机无需访问源码、文档或网络流 量监测就可以发现与理解服务得能力。 Swagger范定义了一组描述一个 API所需得文件格式，类似于描述 Web服务得 WSDL。通过Swagger行REST API得正确定义，用户可以 理解远程服务并使用最少实现逻辑与远程服

18、务进行交互。与为底层编程所 实现得接口类似，Swagge消除了调用服务时可能会有得猜测。 注： Microsoft,PayPal 等公司也已经引入 Swagger 来定义自己得 REST API 文 档。 Swagger API可以使用 YAML或JSON来表示。 Swagge这类API文档工具可以满足下列需求： ? 支持 API 自动生成同步得在线文档 ? 这些文档可用于项目内部 API 审核 ? 方便测试人员了解 API ?这些文档可作为客户产品文档得一部分进行发布 ? 支持 API 规范生成代码，生成得客户端与服务器端骨架代码可以加 速开发与测试速度 通常情况下，API得Swagge描述

19、为JSON文件，也可使用 YAML描 述得文件 附Swagger文件示例: swagger : 2 、 0, info : version : 1、0 、0, title : Swagger Petstore (Simple), description : A sample API that uses a petstore as an 、 0 specification, example to demonstrate features in the swagger-2 termsOfService : , contact : email : url : name: Swagger API te

20、am, , II license : II name: MIT, II url : II II , host : petstore II 、 swagger 、io, basePath : /api, schemes : http , consumes : application/json , produces : application/json , paths : /pets : get : description: Returns all pets from thesystem that the user has access to, operationId: findPets, pro

21、duces : application/json, application/xml, text/xml, text/html , parameters : name : tags, in : query, description : tags to filter by, required : false, type : array, items : type : string , collectionFormat : csv , name: limit, in : query, description : maximum number of results to return, require

22、d : false, type : integer, format : int32 , responses : 200 : description : pet response, schema : type : array, items : $ref : #/definitions/pet , default : description : unexpected error, schema : $ref : #/definitions/errorModel , post : description: Creates a new pet in the store Duplicates are a

23、llowed, operationId: addPet, produces : application/json , parameters : name: pet, in : body, description : Pet to add to the store, required : true, schema : $ref : #/definitions/newPet , responses : 200 : description : pet response, schema : $ref : #/definitions/pet , default : description : unexp

24、ected error, schema : $ref : #/definitions/errorModel , /pets/id : get : description: Returns a user based on a single ID, if the user does not have access to the pet, operationId: findPetById, produces : application/json, application/xml, text/xml, text/html , parameters : name: id, in : path, description : ID of pet to fetch, required : true, type : integer, format : int64 , responses : 200 : description : pet response, schema : $ref : #/definitions/pet , default : description : unexpected error, schema : $ref : #/definitions/errorModel , delete :