RESTfulAPI设计原则与地要求规范Word文件下载.docx

RESTfulAPI设计原则与地要求规范Word文件下载.docx

《RESTfulAPI设计原则与地要求规范Word文件下载.docx》由会员分享，可在线阅读，更多相关《RESTfulAPI设计原则与地要求规范Word文件下载.docx（17页珍藏版）》请在冰豆网上搜索。

是应用程序状态的引擎，资源表示通过超链接互联。

二、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。

4、路径（Endpoints）

路径表示API的具体网址URL。

在RESTful架构中，每个URL代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与代表的对象名称对应。

一般来说，某一同种记录的”集合”（collection），所以API中的名词也应该使用复数。

具体细则：

1、使用名词而不是动词。

举例来说，某个URL是/cards/show/1，其中show是动词，这个URL就设计错了，正确的写法应该是/cards/1，然后用GET方法表示show。

如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。

比如网上汇款，从账户1向账户2汇款500元，错误的URI是：

POST/accounts/1/transfer/500/to/2。

正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：

POST/transaction?

from=1&

to=2&

amount=500.00。

2、使用复数名词。

不要混淆名词单数和复数，为了保持简单，只对所有资源使用复数。

举例：

/cars而不是/car

/users而不是/user

/products而不是/product

/settings而不是/setting

3、使用子资源表达关系。

如果一个资源与另外一个资源有关系，使用子资源。

GET/cars/911/drivers/返回car911的所有司机

GET/cars/911/drivers/8返回car911的8号司机

5、HTTP动词（HTTPVerbs）

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面五个：

•GET（SELECT）：

从服务器取出资源（一项或多项）。

•POST（CREATE）：

在服务器新建一个资源。

•PUT（UPDATE）：

在服务器更新资源（客户端提供改变后的完整资源）。

•PATCH（UPDATE）：

在服务器更新资源（客户端提供改变的属性）。

•DELETE（DELETE）：

从服务器删除资源。

还有两个不常用的HTTP动词。

•HEAD：

获取资源的元数据。

•OPTIONS：

获取信息，关于资源的哪些属性是客户端可以改变的。

Get方法和查询参数不应该涉及状态改变。

使用PUT,POST和DELETE方法而不是GET方法来改变状态。

6、过滤信息（Filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。

API应该提供参数，过滤返回结果。

为集合提供过滤、排序、选择和分页等功能。

下面是一些常见的参数。

•?

limit=10：

指定返回记录的数量

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"

foo@"

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/