当前位置：文档之家 › RESTful-API设计原则与规范

RESTful-API设计原则与规范

  • 格式：docx
  • 大小：2.96 MB
  • 文档页数：18

RESTful-API设计原则与规范RESTful API设计原则与规范一、背景与基础概念 3二、RESTful API应遵循的原则 41、协议(Protocol) 42、域名(ROOT URL) 43、版本(Versioning) 54、路径(Endpoints) 错误!未定义书签。

5、HTTP动词(HTTP Verbs) 错误!未定义书签。

6、过滤信息（Filtering）错误!未定义书签。

7、状态码（Status Codes）88、错误处理（Error handling）99、返回结果（Response）1010、使用HATEOAS的Hypermedia API 1011、认证（Authentication）11三、Swagger API标准11REST，即Representational State Transfer的缩写。

RESTful架构，是目前最流行的一种互联网软件架构。

它结构清晰、符合标准、易于理解、扩展方便，基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制，所以正得到越来越多网站的采用。

如果一个架构符合REST原则，就称它为RESTful架构。

本文即将描述的，即是创建RESTful架构的API所要遵循的原则与规范。

一、背景与基础概念Web 应用程序最重要的REST 原则是，客户端和服务器之间的交互在请求之间是无状态的。

从客户端到服务器的每个请求都必须包含理解请求所必需的信息。

•资源（resource）：网络上的一个实体或者说是一个具体信息，可以是一段文本、一张图片、一首歌曲、一种服务。

•统一资源定位符（URI，Universal Resource Identifier）：一个资源的识别符或者说是一个地址，通过URI你可以定位到特定的资源。

要获取这个资源，需要访问它的URI，因此，URI就成了每一个资源的地址或独一无二的识别符。

•状态转换（State Transfer）: 所有资源都共享统一的接口，以便在客户端和服务器之间传输状态。

客户端与服务器互动的过程，通常涉及到服务器端数据和状态的变化过程，比如文件被修改，访问数量增加等。

使用的是标准的HTTP 方法，Http标准中定义的最主要四个动词：GET、POST、PUT、DELETE。

它们分别对应四种基本操作：-GET：用来获取资源-POST：用来新建资源-PUT：用来更新资源-DELETE：用来删除资源•Hypermedia 是应用程序状态的引擎，资源表示通过超链接互联。

二、RESTful API应遵循的原则1、协议(Protocol)API与用户的通信协议，尽量使用HTTPs协议。

HTTPs协议的所有信息都是加密传播，第三方无法窃听，具有校验机制，一旦被篡改，通信双方会立刻发现，配备身份证书，防止身份被冒充。

2、域名(ROOT URL)应该尽量将API部署在专用域名之下。

https://如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

https:///api/3、版本(Versioning)应该将API的版本号放入URL。

https:///v1/另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。

Github采用这种做法。

注：需要注意版本规划，以便以后API的升级和维护。

使得API版本变得强制性，不要发布无版本的API，使用简单数字，避免小数点如2.5。

•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 消费者一个选择字段的能力，这会降低网络流量，提高API可用性。

②为了将总数发给客户端，使用订制的HTTP头：X-Total-Count.7、状态码（Status Codes）服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

•200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

•201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。

•202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）•204 NO CONTENT - [DELETE]：用户删除数据成功。

•400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

•401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。

•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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

8、错误处理（Error handling）如果状态码是4xx，就应该向用户返回出错信息。

尽量使用详细的错误包装信息：{"errors": [{"userMessage": "Sorry, the requested resource does not exist", "internalMessage": "No car found in the database","code": 4xx,"more info": "/api/v1/errors/12345"}]}9、返回结果（Response）服务器返回的数据格式，应该尽量使用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:///zoos","href": "https:///zoos","title": "List of zoos","type": "application/vnd.yourformat+json"}}上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。

rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

11、认证（Authentication）API的身份认证尽量使用OAuth 2.0框架。

三、Swagger API标准API的文档管理和信息描述，将使用Swagger进行。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。

Swagger的目标是对REST API定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。

Swagger规范定义了一组描述一个API所需的文件格式，类似于描述Web服务的WSDL。

通过Swagger进行REST API的正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。

与为底层编程所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。

注：Microsoft,PayPal等公司也已经引入Swagger 来定义自己的REST API 文档。

Swagger API可以使用YAML或JSON来表示。

Swagger这类API文档工具可以满足下列需求：•支持API自动生成同步的在线文档•这些文档可用于项目内部API审核•方便测试人员了解API•这些文档可作为客户产品文档的一部分进行发布•支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度通常情况下，API的Swagger描述为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 example to demonstrate features in the swagger-2.0 specification", "termsOfService": "/terms/","contact": {"name": "Swagger API team","email":"***************","url": "http://swagger.io"},"license": {"name": "MIT","url": "/licenses/MIT"}},"host": "petstore.swagger.io","basePath": "/api","schemes": ["http"],"consumes": ["application/json"],"produces": ["application/json"],"paths": {"/pets": {"get": {"description": "Returns all pets from the system that the user has access to","operationId": "findPets","produces": ["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", "required": 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 allowed","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": "unexpected 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"}}}"description": "deletes a single pet based on the ID supplied","operationId": "deletePet","parameters": [{"name": "id","in": "path","description": "ID of pet to delete","required": true,"type": "integer","format": "int64"}],"responses": {"204": {"description": "pet deleted"},"default": {"description": "unexpected error","schema": {"$ref": "#/definitions/errorModel"}}}}}},"definitions": {"pet": {"type": "object","required": ["id","name"],"properties": {"id": {"type": "integer","format": "int64"},"name": {"type": "string""type": "string"}}},"newPet": {"type": "object","required": ["name"],"properties": {"id": {"type": "integer", "format": "int64" },"name": {"type": "string"},"tag": {"type": "string"}}},"errorModel": {"type": "object","required": ["code","message"],"properties": {"code": {"type": "integer", "format": "int32" },"message": {"type": "string"}}}}}Swagger文件的构成以及规范信息，在Swagger官方的规范指导《Swagger RESTful API文档规范》中有详细描述，请参看。

合集下载

RESTfulAPI接口设计规范

RESTfulAPI接口设计规范

RESTfulAPI接⼝设计规范 ⽹络应⽤程序，分为前端和后端两个部分。

当前的发展趋势，就是前端设备层出不穷（⼿机、平板、桌⾯电脑、其他专⽤设备…）。

因此，必须有⼀种统⼀的机制，⽅便不同的前端设备与后端进⾏通信。

这导致API构架的流⾏，甚⾄出现"API First"的设计思想。

RESTful API是⽬前⽐较成熟的⼀套互联⽹应⽤程序的API设计理论。

REST（Representational State Transfer）表述性状态转换，REST指的是⼀组架构约束条件和原则。

如果⼀个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

REST本⾝并没有创造新的技术、组件或服务，⽽隐藏在RESTful背后的理念就是使⽤Web的现有特征和能⼒，更好地使⽤现有Web标准中的⼀些准则和约束。

虽然REST 本⾝受Web技术的影响很深，但是理论上REST架构风格并不是绑定在HTTP上，只不过⽬前HTTP是唯⼀与REST相关的实例。

⼀、URI URI 表⽰资源，资源⼀般对应服务器端领域模型中的实体类。

⼀般规范：1、不⽤⼤写；2、⽤中杠 - 不⽤下杠 _；3、参数列表要encode；4、URI中的名词表⽰资源集合，使⽤复数形式。

5、URI表⽰资源的两种⽅式：资源集合、单个资源。

资源集合： /zoos //所有动物园 /zoos/1/animals //id为1的动物园中的所有动物 单个资源： /zoos/1 //id为1的动物园 /zoos/1;2;3 //id为1，2，3的动物园6、避免层级过深的Uri / 在url中表达层级，⽤于按实体关联关系进⾏对象导航，⼀般根据id导航。

过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4，尽量使⽤查询参数代替路径中的实体导航，如GET /animals?zoo=1&area=3；7、对组合资源的访问 服务器端的组合实体必须在uri中通过⽗实体的id导航访问。

RESTful接口规范与设计

RESTful接口规范与设计

RESTful接口规范与设计RESTful（Representational State Transfer）是一种面向资源的软件架构风格，在Web服务的开发中被广泛应用。

本文将介绍RESTful接口的规范与设计原则，以帮助开发者更好地构建高质量的接口。

一、RESTful接口介绍RESTful接口是基于HTTP协议的一种软件架构，它以资源为核心，通过HTTP方法来对资源进行CRUD操作（包括创建、读取、更新和删除）。

RESTful接口的核心概念包括资源、URI、HTTP方法和状态码。

二、RESTful接口设计原则1. 使用名词来表示资源，URI应该简洁且易读，不应包含动词。

2. 使用HTTP方法对资源进行操作，GET用于获取资源，POST用于创建资源，PUT用于更新资源，DELETE用于删除资源。

3. 使用状态码来表示请求的结果，如200表示请求成功，404表示资源不存在，500表示服务器错误等。

4. 接口应该具有自描述性，响应消息的格式应该清晰明确，以方便开发者理解和使用。

5. 接口应该遵循统一的错误处理机制，如使用统一的错误代码和错误信息格式，方便开发者对错误进行处理。

6. 接口应该支持版本管理，通过在URI中引入版本号来实现接口升级和向后兼容。

三、RESTful接口规范1. URI设计规范- 使用名词来表示资源，采用复数形式。

- 使用斜杠“/”来表示资源间的层级关系。

- 避免在URI中出现动词，应该使用HTTP方法来表示操作。

- URI中不应包含文件扩展名。

- 避免在URI中出现冗余信息，如套嵌的子资源应该直接使用父资源的URI加上子资源的标识符。

2. HTTP方法的使用规范- GET方法用于获取资源，不应有副作用，保持幂等性。

- POST方法用于创建资源，应在响应头部返回新资源的URI。

- PUT方法用于更新资源，URI应定位到具体的资源。

- DELETE方法用于删除资源，URI应定位到具体的资源。

RESTfulAPI设计的实现方法与应用

RESTfulAPI设计的实现方法与应用

RESTfulAPI设计的实现方法与应用RESTful API（Representational State Transfer API）是一种基于HTTP/HTTPS协议的API设计风格。

它的设计目的是让网络应用程序能够轻松地实现可伸缩性、可重复使用性、模块化和可定制化等特性。

本文将介绍RESTful API的设计实现方法与应用。

一、设计原则RESTful API的设计原则主要包括以下几点：1.资源导向：RESTful API的设计思想是将每个API都视为一个资源，每个资源都有自己的唯一URI（统一资源标识符）。

2.HTTP动词：RESTful API的设计中，基本的CRUD操作（Create、Read、Update、Delete）通过HTTP的四种方法（POST、GET、PUT、DELETE）来实现。

POST用于新建资源、PUT用于更新资源、GET用于获取资源，DELETE用于删除资源。

3.无状态：每个请求都包含足够的信息，以便服务器能够处理请求。

服务器不会记录任何会话或任何其他与请求有关的信息。

4.客户端–服务器分离：RESTful API的客户、服务器分离性很强。

客户端处理用户交互，服务器处理数据存储等工作。

5.缓存：服务器可以缓存请求的响应以提高性能。

6.层次结构：RESTful API可以使用多层结构，以便能够实现更高级别的功能。

二、实现方法1.URI命名RESTful API的URIs必须包含所请求资源的信息，并通过明确的定义，将请求资源的特定视图捆绑到单个URI上。

URI必须使用名词而不是动词命名。

2.资源参数RESTful API的请求必须包含完整的资源信息，包括设置资源属性值和其他相关信息。

3.响应码RESTful API必须返回合适和合法的HTTP响应码，如200、201、204、400、401、404等。

4.消息体格式RESTful API的请求和响应都必须基于json或xml格式，以便进行传输和解析。

resful api接口定义规则

resful api接口定义规则

resful api接口定义规则
RESTful API 是一种设计风格，用于构建基于 HTTP 协议的网络应用程序接口。

它有一些定义规则，包括以下几点：
1. 使用 HTTP 方法来定义操作，RESTful API 使用 HTTP 方法来表示对资源的不同操作。

常用的 HTTP 方法包括 GET（获取资源）、POST（创建资源）、PUT（更新资源）、DELETE（删除资源）等。

2. 使用 URI 来标识资源，每个资源都有一个唯一的标识符，称为 URI（统一资源标识符）。

在 RESTful API 中，URI 应该清晰地表达资源的层级结构和关系，以便客户端能够通过 URI 定位到所需的资源。

3. 使用状态码来表示结果，RESTful API 使用标准的 HTTP 状态码来表示操作的结果，如 200（成功）、201（已创建）、400（错误的请求）、404（未找到）等。

4. 使用 JSON 或 XML 来传输数据，RESTful API 通常使用JSON 或 XML 格式来传输数据，这两种格式都能很好地表示数据结
构，并且易于解析和处理。

5. 无状态性，RESTful API 是无状态的，即每个请求都应该包含足够的信息，使得服务器能够理解并处理该请求，而不需要依赖之前的请求状态。

6. 使用超媒体作为应用状态的引擎（HATEOAS），这是RESTful API 的一个重要概念，即客户端通过服务器返回的超媒体信息来发现和使用可用的操作。

总的来说，RESTful API 的设计规则旨在使接口清晰、易于理解和使用，同时也能够提供灵活性和扩展性。

这些规则有助于开发人员构建出易于维护和扩展的 API，并且能够为客户端提供良好的用户体验。