RESTfulAPI设计原则与规范Word文档格式.docx

1、-POST： 用来新建资源-PUT： 用来更新资源-DELETE： 用来删除资源Hypermedia是应用程序状态的引擎，资源表示通过超链接互联。二、RESTful API应遵循的原则1、协议（Protocol）API与用户的通信协议，尽量使用HTTPs协议。HTTPs协议的所有信息都是加密传播，第三方无法窃听，具有校验机制，一旦被篡改，通信双方会立刻发现，配备身份证书，防止身份被冒充。2、域名（ROOT URL）应该尽量将API部署在专用域名之下。如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。https:/example.org/api/3、版本（Versioning）应该将

2、API的版本号放入URL。另一种做法是，将版本号放在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 /z

3、oo/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：用户新建或修改数

4、据成功。202 Accepted - *：表示一个请求已经进入后台排队（异步任务）204 NO CONTENT - DELETE：用户删除数据成功。400 INVALID REQUEST - POST/PUT/PATCH：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。401 Unauthorized - *：表示用户没有权限（令牌、用户名、密码错误）。403 Forbidden - *：表示用户得到授权（与401错误相对），但是访问是被禁止的。404 NOT FOUND - *：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。406 Not

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

6、 resource does not exist,internalMessageNo car found in the databasecode 4xx,more info 9、返回结果（Response）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。针对不同操作，服务器向用户返回的结果应该符合以下规范。GET /collection：返回资源对象的列表（数组）GET /collection/resource：返回单个资源对象POST /collection：返回新生成的资源对象PUT /collection/resource：返回完整的资源对象PATCH /collection

7、/resource：DELETE /collection/resource：返回一个空文档10、使用HATEOAS的Hypermedia APIRESTful API最好使用Hypermedia as the Engine of Application State（超媒体作为应用状态的引擎），即返回结果中提供链接，连向其他API方法，超文本链接可以建立更好的文本浏览，使得用户不查文档，也知道下一步应该做什么。比如，当用户向的根目录发出请求，会得到这样一个文档。linkrelcollection hreftitleList of zoostypeapplication/vnd.yourforma

8、t+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定义一个标

9、准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。Swagger规范定义了一组描述一个API所需的文件格式，类似于描述Web服务的WSDL。通过Swagger进行REST API的正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。Microsoft,PayPal等公司也已经引入Swagger 来定义自己的REST API 文档。Swagger API可以使用YAML或JSON来表示。Swagger这类API文档工具可以满足下列需求：支持API自动生成同步的

10、在线文档这些文档可用于项目内部API审核方便测试人员了解API这些文档可作为客户产品文档的一部分进行发布支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度通常情况下，API的Swagger描述为JSON文件，也可使用YAML描述的文件。附Swagger文件示例：swagger2.0infoversion1.0.0Swagger Petstore （Simple）descriptionA sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 spe

11、cificationtermsOfServicecontactnameSwagger API teamemail*urlhttp:/swagger.io ,licenseMIT/opensource.org/licenses/MIThostpetstore.swagger.iobasePath/apischemeshttp ,consumesapplication/jsonproducespaths/petsgetReturns all pets from the system that the user has access tooperationIdfindPetsapplication/

12、xmltext/xmltext/htmlparameterstagsinquerytags to filter byrequired false,arrayitemsstringcollectionFormatcsvlimitmaximum number of results to returnintegerformatint32responses200pet responseschema$ref#/definitions/petdefaultunexpected error#/definitions/errorModelpostCreates a new pet in the store.

13、Duplicates are allowedaddPetpetbodyPet to add to the store true,#/definitions/newPet/pets/idReturns a user based on a single ID, if the user does not have access to the petfindPetByIdidpathID of pet to fetchint64deletedeletes a single pet based on the ID supplieddeletePetID of pet to delete204pet deleteddefinitionsobjectpropertiestagnewPeterrorModelmessageSwagger文件的构成以及规范信息，在Swagger官方的规范指导Swagger RESTful API文档规范中有详细描述，请参看。/swagger.io/specification/