普陀手机网站建设,纺织面料做哪个网站好,wordpress破解管理员密码,杭州小程序网站开发公司1. 简介
目前 互联网软件从用客户端/服务端模式#xff0c;建立在分布式体系上#xff0c;通过互联网通讯#xff0c;具有高延时、高开发等特点。但是软件开发和网络是两个不同的领域#xff0c;交集很少。要使得两个融合#xff0c;就要考虑如何在互联网环境…1. 简介
目前 互联网软件从用客户端/服务端模式建立在分布式体系上通过互联网通讯具有高延时、高开发等特点。但是软件开发和网络是两个不同的领域交集很少。要使得两个融合就要考虑如何在互联网环境使用软件。
REST 描述了一个架构样式的网络系统2000 年 Roy Fielding 在他的博士论文中首次提出了 REST同时他也是HTTP协议1.0版和1.1版的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。
目前主流的三种 Web 服务交互方案
REST表现层状态转化SOAPSimple Object Access protocol简单对象访问协议XML-RPC 要想理解什么是 REST(Representational State Transfe) 就要理解这里几个词是什么意思。
资源Resources
REST的名称表现层状态转化中省略了主语。“表现层其实指的是资源”Resources的表现层。
网络中所谓资源即实体表现的一种如文本、图片、音频视频等。通过调用特定的 URI 来获取相应资源因此 URI 就成了每一个资源的地址或独一无二的识别符。 表现层Representation
“资源是一种信息实体它可以有多种外在表现形式。我们把资源具体呈现出来的形式叫做它的表现层”Representation。
如文本可以以 txt、json、xml 等格式表现甚至是二进制格式图片也有 jpg、png 等格式。
URI 只代表资源的实体不代表它的形式。严格地说有些网址最后的.html 后缀名是不必要的因为这个后缀名表示格式属于表现层范畴而URI应该只代表资源的位置。它的具体表现形式应该在HTTP请求的头信息中用 Accept 和 Content-Type字段指定这两个字段才是对表现层的描述。 状态转化State Transfer
众所周知互联网通讯协议 HTTP 协议是无状态的所有状态都保存在服务器上。因此如果客户端要想操作获取、删除、更新操作数据就必须让服务器状态发生改变State Transfer而这种状态转化建立在表现层上所有称为 表现层状态转化。
客户端通过 HTTP 协议可以与服务端进行通信HTTP 协议中表示操作的四个动作是
GET获取资源POST新建资源PUT更新资源DELETE删除资源
客户端用到的手段只能是HTTP协议。具体来说就是HTTP协议里面四个表示操作方式的动词GET、POST、PUT、DELETE。它们分别对应四种基本操作GET用来获取资源POST用来新建资源也可以用于更新资源PUT用来更新资源DELETE用来删除资源。 RESTful架构典型的设计误区
1、URI 中包含动词资源是一种实体应该用名词动词应放在 HTTP 协议中。
# 错误show 为动词
/posts/show/1# 如果要获取可用 get
/posts/1
/get/ # 表示 show 若某些动作用 HTTP 动词表示不了可用将动作看做一种资源如网上付款 URI 设计
# 错误
POST /accounts/1/transfer/500/to/2# 正确
POST /transaction HTTP/1.1
Host: 127.0.0.1from1to2amount500.002、在 URI 中加入版本号
# 错误
http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo不同的版本可以理解成同一种资源的不同表现形式所以应该采用同一个U RI。版本号可以在HTTP请求头信息的Accept字段中进行区分参见 Versioning REST Services
# 正确
Accept: vnd.example-com.foojson; version1.0
Accept: vnd.example-com.foojson; version1.1然而实际开发中大多开发人员会将版本号放在 URI 中因为方便。 总结
什么是 RESTful 架构
RESTful 是一种在网络上能够开发软件的体系架构互联网之间通讯是资源的一种交互每个 URI 代表一种资源通过特定 URI 可以访问相应资源资源有不同的表现形式HTTP 协议无状态客户端获取服务器资源需要改变其状态客户端通过四个HTTP动词对服务器端资源进行操作实现表现层状态转化
2. RESTful API 设计指南
2.1 协议
API与用户的通信协议总是使用HTTPs协议。
2.2 域名
1、应该尽量将 API 部署在专用域名之下(这中情况会存在跨域问题)
https://api.example.com2、如果确定 API 很简单不会有进一步扩展可以考虑放在主域名下。
https://example.org/api/2.3 版本Versioning
应该将 API 的版本号放入 URL。
https://api.example.com/v1/另一种做法是将版本号放在HTTP头信息中但不如放入URL方便和直观。Github采用这种做法。
2.4 路径Endpoint
路径又称终点endpoint表示 API 的具体网址。
在 RESTful 架构中每个网址代表一种资源resource所以网址中不能有动词只能有名词而且所用的名词往往与数据库的表格名对应。一般来说数据库中的表都是同种记录的集合collection所以 API 中的名词也应该使用复数。
举例来说有一个API提供动物园zoo的信息还包括各种动物和雇员的信息则它的路径应该设计成下面这样。
https://api.example.com/v1/zooshttps://api.example.com/v1/animalshttps://api.example.com/v1/employees
2.5 HTTP动词
对于资源的具体操作类型由 HTTP 动词表示。常用的 HTTP 动词有下面五个括号里是对应的SQL命令
GETSELECT从服务器取出资源一项或多项。POSTCREATE在服务器新建一个资源。PUTUPDATE在服务器更新资源客户端提供改变后的完整资源。PATCHUPDATE在服务器更新资源客户端提供改变的属性。DELETEDELETE从服务器删除资源。
不常用的 HTTP 动词
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删除某个指定动物园的指定动物
2.6 过滤信息Filtering
如果记录数量很多服务器不可能都将它们返回给用户。API 应该提供参数过滤返回结果。
下面是一些常见的参数
# 指定返回记录的数量
https://api.example.com/v1/zoos?limit10# 指定返回记录的开始位置
https://api.example.com/v1/zoos?offset10# 指定第几页以及每页的记录数
https://api.example.com/v1/zoos?page2per_page100# 指定返回结果按照哪个属性排序以及排序顺序
https://api.example.com/v1/zoos?sortbynameorderasc# 指定筛选条件
https://api.example.com/v1/zoos?animal_type_id1参数的设计允许存在冗余即允许API路径和URL参数偶尔有重复。比如GET /zoo/ID/animals 与 GET /animals?zoo_idID 的含义是相同的。
2.7 状态码Status Codes
服务器向用户返回的状态码和提示信息常见的有以下一些方括号中是该状态码对应的HTTP动词。
200 OK - [GET]服务器成功返回用户请求的数据该操作是幂等的Idempotent。201 CREATED - [POST/PUT/PATCH]用户新建或修改数据成功。202 Accepted - [*]表示一个请求已经进入后台排队异步任务204 NO CONTENT - [DELETE]用户删除数据成功。400 INVALID REQUEST - [POST/PUT/PATCH]用户发出的请求有错误服务器没有进行新建或修改数据的操作该操作是幂等的。401 Unauthorized - [*]表示用户没有权限令牌、用户名、密码错误。403 Forbidden - [*] 表示用户得到授权与401错误相对但是访问是被禁止的。404 NOT FOUND - [*]用户发出的请求针对的是不存在的记录服务器没有进行操作该操作是幂等的。406 Not Acceptable - [GET]用户请求的格式不可得比如用户请求JSON格式但是只有XML格式。410 Gone -[GET]用户请求的资源被永久删除且不会再得到的。422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时发生一个验证错误。500 INTERNAL SERVER ERROR - [*]服务器发生错误用户将无法判断发出的请求是否成功。
状态码的完全列表参见这里。
2.8 错误处理Error handling
如果状态码是4xx就应该向用户返回出错信息。一般来说返回的信息中将 error 作为键名出错信息作为键值即可。
{error: Invalid API key
}2.9 返回结果
针对不同操作服务器向用户返回的结果应该符合以下规范。
GET /collection返回资源对象的列表数组GET /collection/resource返回单个资源对象POST /collection返回新生成的资源对象PUT /collection/resource返回完整的资源对象PATCH /collection/resource返回完整的资源对象DELETE /collection/resource返回一个空文档
2.10 Hypermedia API
RESTful API最好做到 Hypermedia即返回结果中提供链接连向其他 API方法使得用户不查文档也知道下一步应该做什么。
比如当用户向 api.example.com的根目录发出请求会得到这样一个文档。
{link: {rel: collection https://www.example.com/zoos,href: https://api.example.com/zoos,title: List of zoos,type: application/vnd.yourformatjson
}}上面代码表示文档中有一个 link 属性用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系collection关系并给出该collection的网址href表示API的路径title表示API的标题type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计访问api.github.com会得到一个所有可用API的网址列表。
{current_user_url: https://api.github.com/user,authorizations_url: https://api.github.com/authorizations,// ...
}从上面可以看到如果想获取当前用户的信息应该去访问api.github.com/user然后就得到了下面结果。
{message: Requires authentication,documentation_url: https://developer.github.com/v3
}上面代码表示服务器给出了提示信息以及文档的网址。
其他
1API 的身份认证应该使用OAuth 2.0框架。
2服务器返回的数据格式应该尽量使用JSON避免使用XML。
