RESTfulAPI设计原则与规范Word文档格式.docx
《RESTfulAPI设计原则与规范Word文档格式.docx》由会员分享，可在线阅读，更多相关《RESTfulAPI设计原则与规范Word文档格式.docx（15页珍藏版）》请在冰豆网上搜索。
-POST：
用来新建资源
-PUT：
用来更新资源
-DELETE：
用来删除资源
•Hypermedia
是应用程序状态的引擎，资源表示通过超链接互联。
二、RESTfulAPI应遵循的原则
1、协议（Protocol）
API与用户的通信协议，尽量使用HTTPs协议。
HTTPs协议的所有信息都是加密传播，第三方无法窃听，具有校验机制，一旦被篡改，通信双方会立刻发现，配备身份证书，防止身份被冒充。
2、域名（ROOTURL）
应该尽量将API部署在专用域名之下。
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
https:
//example.org/api/
3、版本（Versioning）
应该将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/zoo/ID/animals与GET/animals?
zoo_id=ID的含义是相同的
①移动端能够显示其中一些字段，它们其实不需要一个资源的所有字段，给API消费者一个选择字段的能力，这会降低网络流量，提高API可用性。
②为了将总数发给客户端，使用订制的HTTP头：
X-Total-Count.
7、状态码（StatusCodes）
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。
•200OK-[GET]：
服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
•201CREATED-[POST/PUT/PATCH]：
用户新建或修改数据成功。
•202Accepted-[*]：
表示一个请求已经进入后台排队（异步任务）
•204NOCONTENT-[DELETE]：
用户删除数据成功。
•400INVALIDREQUEST-[POST/PUT/PATCH]：
用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
•401Unauthorized-[*]：
表示用户没有权限（令牌、用户名、密码错误）。
•403Forbidden-[*]：
表示用户得到授权（与401错误相对），但是访问是被禁止的。
•404NOTFOUND-[*]：
用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
•406NotAcceptable-[GET]：
用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
•410Gone-[GET]：
用户请求的资源被永久删除，且不会再得到的。
•422Unprocesableentity-[POST/PUT/PATCH]：
当创建一个对象时，发生一个验证错误。
•500INTERNALSERVERERROR-[*]：
服务器发生错误，用户将无法判断发出的请求是否成功。
8、错误处理（Errorhandling）
如果状态码是4xx，就应该向用户返回出错信息。
尽量使用详细的错误包装信息：
{
"
errors"
:
[
{
userMessage"
Sorry,therequestedresourcedoesnotexist"
internalMessage"
Nocarfoundinthedatabase"
code"
4xx,
moreinfo"
}
]
}
9、返回结果（Response）
服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
针对不同操作，服务器向用户返回的结果应该符合以下规范。
•GET/collection：
返回资源对象的列表（数组）
•GET/collection/resource：
返回单个资源对象
•POST/collection：
返回新生成的资源对象
•PUT/collection/resource：
返回完整的资源对象
•PATCH/collection/resource：
•DELETE/collection/resource：
返回一个空文档
10、使用HATEOAS的HypermediaAPI
RESTfulAPI最好使用HypermediaastheEngineofApplicationState（超媒体作为应用状态的引擎），即返回结果中提供链接，连向其他API方法，超文本链接可以建立更好的文本浏览，使得用户不查文档，也知道下一步应该做什么。
比如，当用户向的根目录发出请求，会得到这样一个文档。
{"
link"
rel"
collection
href"
title"
Listofzoos"
type"
application/vnd.yourformat+json"
}}
上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。
rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。
11、认证（Authentication）
API的身份认证尽量使用OAuth2.0框架。
三、SwaggerAPI标准
API的文档管理和信息描述，将使用Swagger进行。
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。
Swagger的目标是对RESTAPI定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。
Swagger规范定义了一组描述一个API所需的文件格式，类似于描述Web服务的WSDL。
通过Swagger进行RESTAPI的正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。
与为底层编程所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。
Microsoft,PayPal等公司也已经引入Swagger来定义自己的RESTAPI文档。
SwaggerAPI可以使用YAML或JSON来表示。
Swagger这类API文档工具可以满足下列需求：
•支持API自动生成同步的在线文档
•这些文档可用于项目内部API审核
•方便测试人员了解API
•这些文档可作为客户产品文档的一部分进行发布
•支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度
通常情况下，API的Swagger描述为JSON文件，也可使用YAML描述的文件。
附Swagger文件示例：
swagger"
2.0"
info"
version"
1.0.0"
SwaggerPetstore（Simple）"
description"
AsampleAPIthatusesapetstoreasanexampletodemonstratefeaturesintheswagger-2.0specification"
termsOfService"
contact"
name"
SwaggerAPIteam"
email"
***************"
url"
http:
//swagger.io"
},
license"
MIT"
//opensource.org/licenses/MIT"
host"
petstore.swagger.io"
basePath"
/api"
schemes"
http"
],
consumes"
application/json"
produces"
paths"
/pets"
get"
Returnsallpetsfromthesystemthattheuserhasaccessto"
operationId"
findPets"
application/xml"
text/xml"
text/html"
parameters"
tags"
in"
query"
tagstofilterby"
required"
false,
array"
items"
string"
collectionFormat"
csv"
limit"
maximumnumberofresultstoreturn"
integer"
format"
int32"
responses"
200"
petresponse"
schema"
$ref"
#/definitions/pet"
default"
unexpectederror"
#/definitions/errorModel"
post"
Createsanewpetinthestore.Duplicatesareallowed"
addPet"
pet"
body"
Pettoaddtothestore"
true,
#/definitions/newPet"
/pets/{id}"
ReturnsauserbasedonasingleID,iftheuserdoesnothaveaccesstothepet"
findPetById"
id"
path"
IDofpettofetch"
int64"
delete"
deletesasinglepetbasedontheIDsupplied"
deletePet"
IDofpettodelete"
204"
petdeleted"
definitions"
object"
properties"
tag"
newPet"
errorModel"
message"
Swagger文件的构成以及规范信息，在Swagger官方的规范指导《SwaggerRESTfulAPI文档规范》中有详细描述，请参看。
//swagger.io/specification/
升级会员 