《RESTful-API设计原则与规范》由会员分享，可在线阅读，更多相关《RESTful-API设计原则与规范（19页珍藏版）》请在金锄头文库上搜索。
1、RESTful-API设计原则与规范34445错误！未定义书签。错误！未定义书签。错误！未定义书签。8910101111RESTful API 设计原则与规范一、背景与基础概念二、 RESTful API 应遵循的原则1 、协议(Protocol)2 、域名(ROOT URL)3 、版本(Versioning)4 、路径(Endpoints)5 、 HTTP 动词 (HTTP Verbs)6 、过滤信息(Filtering )7 、状态码( Status Codes )8 、错误处理(Error handling )9 、返回结果(Response )10 、使用 HATEOAS 的 Hype
2、rmedia API11 、认证( Authentication )三、 Swagger API 标准REST,即 Representational State Transfe的缩写。RESTful 架构，是目 前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制，所以正得到越来越多网站的采用。如果一个架构符合REST 原则，就称它为 RESTful 架构。本文即将描述的，即是创建RESTful 架构的 API 所要遵循的原则与规范。一、背景与基础概念Web 应用程序最重要的 REST 原则是， 客户端和服务器
3、之间的交互在请求之间是无状态的。从客户端到服务器的每个请求都必须包含理解请求所必需的信息。?资源(resource :网络上的一个实体或者说是一个具体信息，可以是一段文本、一张图片、一首歌曲、一种服务。?统一资源定位符(URI, Universal Resource Identifier : 一个资源的识别符或者说是一个地址，通过URI 你可以定位到特定的资源。要获取这个资源，需要访问它的 URI ，因此， URI 就成了每一个资源的地址或独一无二的识别符。? 状态转换( State Transfe)r : 所有资源都共享统一的接口，以便在客户端和服务器之间传输状态。客户端与服务器互动的过程，
4、通常涉及到服务器端数据和状态的变化过程，比如文件被修改，访问数量增加等。使用的是标准的 HTTP 方法， Http 标准中定义的最主要四个动词： GET 、POST、 PUT 、 DELETE 。它们分别对应四种基本操作：- GET ： 用来获取资源- POST： 用来新建资源- PUT ： 用来更新资源- DELETE ： 用来删除资源? Hypermedia是应用程序状态的引擎，资源表示通过超链接互联。二、 RESTful API 应遵循的原则1 、协议 (Protocol)API 与用户的通信协议，尽量使用 HTTPs 协议。 HTTPs 协议的所有信息都是加密传播，第三方无法窃听，具有
5、校验机制，一旦被篡改，通信双方会立刻发现，配备身份证书，防止身份被冒充。2 、域名 (ROOT URL)应该尽量将API 部署在专用域名之下。https:/如果确定 API 很简单，不会有进一步扩展，可以考虑放在主域名下。https:/example.org/api/3 、版本 (Versioning)应该将 API 的版本号放入URL 。https:/ 将版本号放在HTTP 头信息中， 但不如放入 URL 方便和直观。 Github 采用这种做法。注：需要注意版本规划，以便以后 API 的升级和维护。使得 API 版本变得强制性，不要发布无版本的 API ，使用简单数字，避免小数点如 2.5
6、 。4、路径(Endpoints)路径表示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 /accounts/1/transfer/500/to/2o 正确的写法是把 动词transfer改成名词transaction,资源不能是动词，但是可以是一种 服务：POST /transaclion?froin-l&lo=2&amoun 1=500. 00。2、使用复数名词。不要混淆名词单数和复数，为了保持简单，只对所 有资源使用复数。举例：/cars而不是/car/users 而不是 /user/products 而不是 /product/settings 而不是 /setting3、使用子资源表达关系。如果一个资源与另外一个资源有关系，使用子资
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)：在服务器更新资源(客户端提供改变的属性)。 DELETE (DELETE)：从服务器删除资源。
9、还有两个不常用的HTTP动词。 HEAD：获取资源的元数据。 OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。注：Get方法和查询参数不应该涉及状态改变。使用PUT, POST和DELETE方法而不是GET方法来改变状态。6、过滤信息(Filtering)如果记录数量很多，服务器不可能都将它们返回给用户。API应该提 供参数，过滤返回结果。为集合提供过滤、排序、选择和分页等功能。下面是一些常见的参数。 ?limit=10：指定返回记录的数量? ?offset=10：指定返回记录的开始位置? ?pageNumber=2&perSize=10Q指定第几页，以及每页的记录数。? ?s
10、ortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。1 ?animal_type_id=1：指定筛选条件参数的设计允许存在冗余，即允许API 路径和 URL 参数偶尔有重复。比如， GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的注：移动端能够显示其中一些字段， 它们其实不需要一个资源的所有字段， 给 API消费者一个选择字段的能力，这会降低网络流量，提高 API 可用性。为了将总数发给客户端，使用订制的HTTP头：X-Total-Count.7 、状态码（ Status Codes ）服务器向用户返回的
11、状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的 HTTP 动词）。? 200 OK - GET ：服务器成功返回用户请求的数据，该操作是幂等的（ Idempotent ）。? 201 CREATED - POST/PUT/PATCH ：用户新建或修改数据成功。? 202 Accepted - *：表示一个请求已经进入后台排队（异步任务）? 204 NO CONTENT - DELETE ：用户删除数据成功。? 400 INVALID REQUEST - POST/PUT/PATCH ：用户发出的请求有错误，服 务器没有进行新建或修改数据的操作，该操作是幂等的。? 401 Unau
12、thorized - *：表示用户没有权限（令牌、用户名、密码错误）。? 403 Forbidden - * ：表示用户得到授权（与401 错误相对），但是访问是被禁止的。? 404 NOT FOUND - * ：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。? 406 Not Acceptable - GET:用户请求的格式不可得（比如用户请求JSON格式,但是只有 XML 格式）。? 410 Gone -GET ：用户请求的资源被永久删除，且不会再得到的。? 422 Unprocesable entity - POST/PUT/PATCH ： 当创建一个对象时，
13、发生一个验证错误。? 500 INTERNAL SERVER ERROR - * ：服务器发生错误，用户将无法判断发出的请求是否成功。8 、错误处理（ Error handling ）如果状态码是4xx， 就应该向用户返回出错信息。 尽量使用详细的错误包装信息：errors: userMessage: Sorry, the requested resource does not exist,internalMessage: No car found in the database,code: 4xx,more info: http:/ 、返回结果（ Response ）服务器返回的数据格式，应
14、该尽量使用 JSON,避免使用XML。针对 不同操作，服务器向用户返回的结果应该符合以下规范。? GET /collection ：返回资源对象的列表（数组）? GET /collection/resource ：返回单个资源对象? POST /collection ：返回新生成的资源对象? PUT /collection/resource ：返回完整的资源对象? PATCH /collection/resource ：返回完整的资源对象? DELETE /collection/resource ：返回一个空文档10 、使用 HATEOAS 的 Hypermedia APIRESTful API 最好使用 Hypermedia as the Engine of Application State（超 媒体作为应用状态的引擎） ， 即返回结果中提供链接， 连向其他 API 方法， 超文本链接可以建立更好的文本浏览，使得用户不查文档，也知道下一步 应该做什么。比如，当用户向的根目录发出请求，会得到这样一个 文档。link: rel: collection https:/ https:/ List of zoos,type: applicatio
