RestApi开发要求规范.docx

RestApi开发要求规范.docx

《RestApi开发要求规范.docx》由会员分享，可在线阅读，更多相关《RestApi开发要求规范.docx（15页珍藏版）》请在冰点文库上搜索。

RestApi开发要求规范

阮一峰

日期：

2011年9月12日

divclass="asset-body"

越来越多的人开始意识到，即软件，而且是一种新型的软件。

/divdivid="more"class="asset-more"

这种"互联网软件"采用客户端/服务器模式，建立在分布式体系上，通过互联网通信，具有高延时〔highlatency〕、高并发等特点。

开发，完全可以采用软件开发的模式。

但是传统上，软件和网络是两个不同的领域，很少有交集；软件开发主要针对单机环境，网络如此主要研究系统之间的通信。

互联网的兴起，使得这两个领域开始融合，现在我们必须考虑，如何开发在互联网环境中使用的软件。

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

它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多的采用。

但是，到底什么是RESTful架构，并不是一个容易说清楚的问题。

下面，我就谈谈我理解的RESTful架构。

一、起源

REST这个词，是RoyThomasFielding在他2000年的博士论文中提出的。

Fielding是一个非常重要的人，他是协议〔1.0版和1.1版〕的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。

所以，他的这篇论文一经发表，就引起了关注，并且立即对互联网开发产生了深远的影响。

他这样介绍论文的写作目的：

"本文研究计算机科学两大前沿----软件和网络----的交叉点。

长期以来，软件研究主要关注软件设计的分类、设计方法的演化，很少客观地评估不同的设计选择对系统行为的影响。

而相反地，网络研究主要关注系统之间通信行为的细节、如何改良特定通信机制的表现，常常无视了一个事实，那就是改变应用程序的互动风格比改变互动协议，对整体表现有更大的影响。

我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为根底的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。

"

（Thisdissertationexploresajunctiononthefrontiersoftworesearchdisciplinesinputerscience:

softwareandnetworking.Softwareresearchhaslongbeenconcernedwiththecategorizationofsoftwaredesignsandthedevelopmentofdesignmethodologies,buthasrarelybeenabletoobjectivelyevaluatetheimpactofvariousdesignchoicesonsystembehavior.Networkingresearch,incontrast,isfocusedonthedetailsofgenericmunicationbehaviorbetweensystemsandimprovingtheperformanceofparticularmunicationtechniques,oftenignoringthefactthatchangingtheinteractionstyleofanapplicationcanhavemoreimpactonperformancethanthemunicationprotocolsusedforthatinteraction.Myworkismotivatedbythedesiretounderstandandevaluatethearchitecturaldesignofnetwork-basedapplicationsoftwarethroughprincipleduseofarchitecturalconstraints,therebyobtainingthefunctional,performance,andsocialpropertiesdesiredofanarchitecture.）

二、名称

Fielding将他对互联网软件的架构原如此，定名为REST，即RepresentationalStateTransfer的缩写。

我对这个词组的翻译是"表现层状态转化"。

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

要理解RESTful架构，最好的方法就是去理解RepresentationalStateTransfer这个词组到底是什么意思，它的每一个词代表了什么涵义。

如果你把这个名称搞懂了，也就不难体会REST是一种什么样的设计。

三、资源〔Resources〕

REST的名称"表现层状态转化"中，省略了主语。

"表现层"其实指的是"资源"〔Resources〕的"表现层"。

所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。

它可以是一段文本、一X图片、一首歌曲、一种服务，总之就是一个具体的实在。

你可以用一个URI〔统一资源定位符〕指向它，每种资源对应一个特定的URI。

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

所谓"上网"，就是与互联网上一系列的"资源"互动，调用它的URI。

四、表现层〔Representation〕

"资源"是一种信息实体，它可以有多种外在表现形式。

我们把"资源"具体呈现出来的形式，叫做它的"表现层"〔Representation〕。

比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。

URI只代表资源的实体，不代表它的形式。

严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"X畴，而URI应该只代表"资源"的位置。

它的具体表现形式，应该在请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。

五、状态转化〔StateTransfer〕

访问一个，就代表了客户端和服务器的一个互动过程。

在这个过程中，势必涉与到数据和状态的变化。

互联网通信协议协议，是一个无状态协议。

这意味着，所有的状态都保存在服务器端。

因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"〔StateTransfer〕。

而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。

客户端用到的手段，只能是协议。

具体来说，就是协议里面，四个表示操作方式的动词：

GET、POST、PUT、DELETE。

它们分别对应四种根本操作：

GET用来获取资源，POST用来新建资源〔也可以用于更新资源〕，PUT用来更新资源，DELETE用来删除资源。

六、综述

综合上面的解释，我们总结一下什么是RESTful架构：

　　〔1〕每一个URI代表一种资源；

　　〔2〕客户端和服务器之间，传递这种资源的某种表现层；

　　〔3〕客户端通过四个动词，对服务器端资源进展操作，实现"表现层状态转化"。

七、误区

RESTful架构有一些典型的设计误区。

最常见的一种设计错误，就是URI包含动词。

因为"资源"表示一种实体，所以应该是名词，URI不应该有动词，动词应该放在协议中。

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

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

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

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

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

另一个设计误区，就是在URI中参加版本号：

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。

版本号可以在请求头信息的Accept字段中进展区分〔参见VersioningRESTServices〕：

〔完〕

************************************************************************

阮一峰

日期：

2014年5月22日

divclass="asset-body"

网络应用程序，分为前端和后端两个局部。

当前的开展趋势，就是前端设备层出不穷〔手机、平板、桌面电脑、其他专用设备......〕。

/divdivid="more"class="asset-more"

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

这导致API构架的流行，甚至出现"APIFirst"的设计思想。

RESTfulAPI是目前比拟成熟的一套互联网应用程序的API设计理论。

我以前写过一篇《理解RESTful架构》，探讨如何理解这个概念。

今天，我将介绍RESTfulAPI的设计细节，探讨如何设计一套合理、好用的API。

我的主要参考了两篇文章〔1，2〕。

一、协议

API与用户的通信协议，总是使用s协议。

二、域名

应该尽量将API部署在专用域名之下。

s:

//api.example.

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

三、版本〔Versioning〕

应该将API的版本号放入URL。

s:

//api.example./v1/

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

Github采用这种做法。

四、路径〔Endpoint〕

路径又称"终点"〔endpoint〕，表示API的具体网址。

在RESTful架构中，每个网址代表一种资源〔resource〕，所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。

一般来说，数据库中的表都是同种记录的"集合"〔collection〕，所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园〔zoo〕的信息，还包括各种动物和雇员的信息，如此它的路径应该设计成下面这样。

∙s:

//api.example./v1/zoos

∙s:

//api.example./v1/animals

∙s:

//api.example./v1/employees

五、动词

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

常用的动词有下面五个〔括号里是对应的SQL命令〕。

∙GET〔SELECT〕：

从服务器取出资源〔一项或多项〕。

∙POST〔CREATE〕：

在服务器新建一个资源。

∙PUT〔UPDATE〕：

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

∙PATCH〔UPDATE〕：

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

∙DELETE〔DELETE〕：

从服务器删除资源。

还有两个不常用的动词。

∙HEAD：

获取资源的元数据。

∙OPTIONS：

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

下面是一些例子。

∙GET/zoos：

列出所有动物园

∙POST/zoos：

新建一个动物园

∙GET/zoos/ID：

获取某个指定动物园的信息

∙PUT/zoos/ID：

更新某个指定动物园的信息〔提供该动物园的全部信息〕

∙PATCH/zoos/ID：

更新某个指定动物园的信息〔提供该动物园的局部信息〕

∙DELETE/zoos/ID：

删除某个动物园

∙GET/zoos/ID/animals：

列出某个指定动物园的所有动物

∙DELETE/zoos/ID/animals/ID：

删除某个指定动物园的指定动物

六、过滤信息〔Filtering〕

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

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

下面是一些常见的参数。

∙?

limit=10：

指定返回记录的数量

∙?

offset=10：

指定返回记录的开始位置。

∙?

page=2&per_page=100：

指定第几页，以与每页的记录数。

∙?

sortby=name&order=asc：

指定返回结果按照哪个属性排序，以与排序顺序。

∙?

animal_type_id=1：

指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。

比如，GET/zoo/ID/animals与GET/animals?

zoo_id=ID的含义是一样的。

七、状态码〔StatusCodes〕

服务器向用户返回的状态码和提示信息，常见的有以下一些〔方括号中是该状态码对应的动词〕。

∙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-[*]：

服务器发生错误，用户将无法判断发出的请求是否成功。

状态码的完全列表参见这里。

八、错误处理〔Errorhandling〕

如果状态码是4xx，就应该向用户返回出错信息。

一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{

  error:

"InvalidAPIkey"

}

九、返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规X。

∙GET/collection：

返回资源对象的列表〔数组〕

∙GET/collection/resource：

返回单个资源对象

∙POST/collection：

返回新生成的资源对象

∙PUT/collection/resource：

返回完整的资源对象

∙PATCH/collection/resource：

返回完整的资源对象

∙DELETE/collection/resource：

返回一个空文档

十、HypermediaAPI

RESTfulAPI最好做到Hypermedia，即返回结果中提供，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

比如，当用户向api.example.的根目录发出请求，会得到这样一个文档。

{"link":

{

 "rel":

 "collections:

//.example./zoos",

 "href":

 "s:

//api.example./zoos",

 "title":

"Listofzoos",

 "type":

 "application/vnd.yourformat+json"

}}

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。

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

HypermediaAPI的设计被称为HATEOAS。

Github的API就是这种设计，访问api.github.会得到一个所有可用API的网址列表。

{

 "current_user_url":

"s:

//api.github./user",

 "authorizations_url":

"s:

//api.github./authorizations",

 //...

}

从上面可以看到，如果想获取当前用户的信息，应该去访问api.github./user，然后就得到了下面结果。

{

 "message":

"Requiresauthentication",

 "documentation_url":

"s:

//developer.github./v3"

}

上面代码表示，服务器给出了提示信息，以与文档的网址。

十一、其他

〔1〕API的身份认证应该使用c:

\iknow\docshare\data\cur_work\.ruanyifeng\blog\2014\05\oauth_2_0.html框架。

〔2〕服务器返回的数据格式，应该尽量使用JSON，防止使用XML。

〔完〕

/div

************************************************************************

WebAPI已经在最近几年变成重要的话题，一个干净的API设计对于后端系统是非常重要的。

　　通常我们为WebAPI使用RESTful设计，REST概念别离了API结构和逻辑资源，通过方法GET,DELETE,POST和PUT来操作资源。

　　下面是进展RESTfulWebAPI十个最优实践，能为你提供一个良好的API设计风格。

Resource

资源

GET

读

POST

创建

PUT

修改

DELETE

/cars

返回cars集合

创建新的资源

批量更新cars

删除所有cars

/cars/711

返回特定的car

该方法不允许（405）

更新一个指定的资源

擅长指定资源

不要使用：

/getAllCars

/createNewCar

/deleteAllRedCars

使用PUT,POST 和DELETE 方法 而不是 GET 方法来改变状态，不要使用GET 进展状态改变:

GET/users/711?

activate 

GET/users/711/activate

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

/cars而不是/car

/users而不是/user

/products而不是/product

/settings而部署/setting

4.使用子资源表达关系

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

GET/cars/711/drivers/返回car711的所有司机

GET/cars/711/drivers/4返回car711的4号司机

在客户端和服务端，双方都要知道通讯的格式，格式在-Header中指定

Content-Type定义请求格式

Accept定义系列可承受的响应格式

Hypermedia as the Engine of Application State超媒体作为应用状态的引擎，超文本可以建立更好的文本浏览：

{

 "id":

711,

 "manufacturer":

"bmw",

 "model":

"X5",

 "seats":

5,

 "drivers":

[

  {

   "id":

"23",

   "name":

"StefanJauker",

   "links":

[

    {

    "rel":

"self",

    "href":

"/api/v1/drivers/23"

   }

  ]

 }

 ]

}

注意href指向下一个URL

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

Filtering过滤:

使用唯一的查询参数进展过滤：

GET/cars?

color=red返回红色的cars

GET/cars?

seats<=2返回小于两座位的cars集合

Sorting排序:

允许针对多个字段排序

GET/cars?

sort=-manufactorer,+model

这是返回根据生产者降序和模型升序排列的car集合

Fieldselection

移动端能够显示其中一些字段，它们其实不需要一个资源的所有字段，给API消费者一个选择字段的能力，这会降低网络流量，提高API可用性。

GET/cars?

fields=manufacturer,model,id,color

Paging分页

使用limit和offset.实现分页，缺省limit=20和offset=0；

GET/cars?

offset=10&limit=5

为了将总数发给客户端，使用订制的头：

X-Total-Count.

到下一页或上一页可以在头的link规定，遵循Link规定:

Link:

//blog.mwaysolutions./sample/api/v1/cars?

offset=15&limit=5>;rel="next",

//blog.mwaysolutions./sample/api/v1/cars?

offset=50&limit=3>;rel="last",

//blog.mwaysolutions./sample/api/v1/cars?

offset=0&limit=5>;rel="first",

//blog.mwaysolutions./sample/api/v1/cars?

offset=5&limit=5>;rel="prev",

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

一般在Url后面使用?

v

/blog/api/v1

9.使用状态码处理错误

如果你的API没有错误处理是很难的，只是返回500和出错堆栈不一定有用

状态码提供70个出错，我们只要使用10个左右：

200–OK–一切正常

201–OK–新的资源已经成功创建

204–OK–资源已经成功擅长

304–NotModified–客户端使用缓存数据

400–BadRequest–请求无效，需要附加细节解释如"JSON无效"

401–Unauthorized–请求需要用户验证

403–Forbidden–服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的。

404–Notfound–没有发现该资源

422–UnprocessableEntity–只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。

500–InternalServerError