RESTful API设计原则与规范.docx
- 文档编号:27770899
- 上传时间:2023-07-04
- 格式:DOCX
- 页数:17
- 大小:21.33KB
RESTful API设计原则与规范.docx
《RESTful API设计原则与规范.docx》由会员分享,可在线阅读,更多相关《RESTful API设计原则与规范.docx(17页珍藏版)》请在冰豆网上搜索。
RESTfulAPI设计原则与规范
RESTfulAPI设计原则与规范
REST,即RepresentationalStateTransfer得缩写。
RESTful架构,就是目前最流行得一种互联网软件架构。
它结构清晰、符合标准、易于理解、扩展方便,基于这个风格设计得软件可以更简洁,更有层次,更易于实现缓存等机制,所以正得到越来越多网站得采用。
如果一个架构符合REST原则,就称它为RESTful架构。
本文即将描述得,即就是创建RESTful架构得API所要遵循得原则与规范。
一、背景与基础概念
Web应用程序最重要得REST原则就是,客户端与服务器之间得交互在请求之间就是无状态得。
从客户端到服务器得每个请求都必须包含理解请求所必需得信息。
•资源(resource):
网络上得一个实体或者说就是一个具体信息,可以就是一段文本、一张图片、一首歌曲、一种服务。
•统一资源定位符(URI,UniversalResourceIdentifier):
一个资源得识别符或者说就是一个地址,通过URI您可以定位到特定得资源。
要获取这个资源,需要访问它得URI,因此,URI就成了每一个资源得地址或独一无二得识别符。
•状态转换(StateTransfer):
所有资源都共享统一得接口,以便在客户端与服务器之间传输状态。
客户端与服务器互动得过程,通常涉及到服务器端数据与状态得变化过程,比如文件被修改,访问数量增加等。
使用得就是标准得HTTP方法,Http标准中定义得最主要四个动词:
GET、POST、PUT、DELETE。
它们分别对应四种基本操作:
-GET:
用来获取资源
-POST:
用来新建资源
-PUT:
用来更新资源
-DELETE:
用来删除资源
•Hypermedia 就是应用程序状态得引擎,资源表示通过超链接互联。
二、RESTfulAPI应遵循得原则
1、协议(Protocol)
API与用户得通信协议,尽量使用HTTPs协议。
HTTPs协议得所有信息都就是加密传播,第三方无法窃听,具有校验机制,一旦被篡改,通信双方会立刻发现,配备身份证书,防止身份被冒充。
2、域名(ROOTURL)
应该尽量将API部署在专用域名之下。
如果确定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":
"、example、com/api/v1/errors/12345"
}
]
}
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方法,超文本链接可以建立更好得文本浏览,使得用户不查文档,也知道下一步应该做什么。
比如,当用户向api、example、com得根目录发出请求,会得到这样一个文档。
{"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",
"title":
"SwaggerPetstore(Simple)",
"description":
"AsampleAPIthatusesapetstoreasanexampletodemonstratefeaturesintheswagger-2、0specification",
"termsOfService":
"",
"contact":
{
"name":
"SwaggerAPIteam",
"email":
"",
"url":
""
},
"license":
{
"name":
"MIT",
"url":
""
}
},
"host":
"petstore、swagger、io",
"basePath":
"/api",
"schemes":
[
"http"
],
"consumes":
[
"application/json"
],
"produces":
[
"application/json"
],
"paths":
{
"/pets":
{
"get":
{
"description":
"Returnsallpetsfromthesystemthattheuserhasaccessto",
"operationId":
"findPets",
"produces":
[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":
[
{
"name":
"tags",
"in":
"query",
"description":
"tagstofilterby",
"required":
false,
"type":
"array",
"items":
{
"type":
"string"
},
"collectionFormat":
"csv"
},
{
"name":
"limit",
"in":
"query",
"description":
"maximumnumberofresultstoreturn",
"required":
false,
"type":
"integer",
"format":
"int32"
}
],
"responses":
{
"200":
{
"description":
"petresponse",
"schema":
{
"type":
"array",
"items":
{
"$ref":
"#/definitions/pet"
}
}
},
"default":
{
"description":
"unexpectederror",
"schema":
{
"$ref":
"#/definitions/errorModel"
}
}
}
},
"post":
{
"description":
"Createsanewpetinthestore、Duplicatesareallowed",
"operationId":
"addPet",
"produces":
[
"application/json"
],
"parameters":
[
{
"name":
"pet",
"in":
"body",
"description":
"Pettoaddtothestore",
"required":
true,
"schema":
{
"$ref":
"#/definitions/newPet"
}
}
],
"responses":
{
"200":
{
"description":
"petresponse",
"schema":
{
"$ref":
"#/definitions/pet"
}
},
"default":
{
"description":
"unexpectederror",
"schema":
{
"$ref":
"#/definitions/errorModel"
}
}
}
}
},
"/pets/{id}":
{
"get":
{
"description":
"ReturnsauserbasedonasingleID,iftheuserdoesnothaveaccesstothepet",
"operationId":
"findPetById",
"produces":
[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":
[
{
"name":
"id",
"in":
"path",
"description":
"IDofpettofetch",
"required":
true,
"type":
"integer",
"format":
"int64"
}
],
"responses":
{
"200":
{
"description":
"petresponse",
"schema":
{
"$ref":
"#/definitions/pet"
}
},
"default":
{
"description":
"unexpectederror",
"schema":
{
"$ref":
"#/definitions/errorModel"
}
}
}
},
"delete":
{
"description":
"deletesasinglepetbasedontheIDsupplied",
"operationId":
"deletePet",
"parameters":
[
{
"name":
"id",
"in":
"path",
"description":
"IDofpettodelete",
"required":
true,
"type":
"integer",
"format":
"int64"
}
],
"responses":
{
"204":
{
"description":
"petdeleted"
},
"default":
{
"description":
"unexpectederror",
"schema":
{
"$ref":
"#/definitions/errorModel"
}
}
}
}
}
},
"definitions":
{
"pet":
{
"type":
"object",
"required":
[
"id",
"name"
],
"properties":
{
"id":
{
"type":
"integer",
"format":
"int64"
},
"name":
{
"type":
"string"
},
"tag":
{
"type":
"string"
}
}
},
"newPet":
{
"type":
"object",
"required":
[
"name"
],
"properties":
{
"id":
{
"type":
"integer",
"format":
"int64"
},
"name":
{
"type":
"string"
},
"tag":
{
"type":
"string"
}
}
},
"errorModel":
{
"type":
"object",
"required":
[
"code",
"message"
],
"properties":
{
"code":
{
"type":
"integer",
"format":
"int32"
},
"message":
{
"type":
"string"
}
}
}
}
}
Swagger文件得构成以及规范信息,在Swagger官方得规范指导《SwaggerRESTfulAPI文档规范》中有详细描述,请参瞧。
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- RESTful API设计原则与规范 API 设计 原则 规范