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