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