API
API是指某个应用程序封装好的一些函数,是提供给其他应用程序或开发人员使用的。通过API,可以方便的使用的本应用程序的功能,而无需了解本应用程序的内部源码。
Web API是API中的一类,它的功能与广义上的API是一样的,只是它提供给外界的是一些url规则而非函数,包括下面4个部分:
url:url链接;
请求方式:get、post、patch、delete等;
请求参数:json或xml格式的key-value类型数据;
响应结果:json或xml格式的key-value类型数据。
REST是REpresentational State Transfer(表述性状态转移)的首字母缩写。它是分布式超媒体系统的架构风格,最初由Roy Fielding在2000年的论文中提出。
1.什么是RESTful:
REST-ful,其中ful代表形容词,如helpful、powerful。这类形容词意为"full of,having the quality of"。多加在名词之后表示“充满…的、易于…、可…的、富有…的、具有…的”的意思,是最常用的形容词后缀,反义词后缀是-less。RESTful 就代表满足REST原则的
参考自:RESTful API
2. 什么是RESTful规范
REST指的是一组架构约束条件和原则,通常用于Web服务的开发。它没有提出具体的实现,只是提出了一些指导规范,供我们开发时参考。我们可以按照它的规范来,也可以忽视(不建议)。
如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构。
3.RESTful API 设计指南
安全保障
为了安全起见,应该使用https协议。
4.表识API
用api关键字标识api url,与普通url加以区别。如:
www.xyz.com/api/xxx/,api.xyz.com/xxx/
5.版本控制
在url中添加版本版本,或者将版本信息放在请求头中,请求同一资源的不同版本。如:
api.xyz.com/v1/xxx,Accept: application/vnd.xyz+json;version=1.0。
6.路径
数据即是资源,应当使用名词(可用复数形式)。如:www.xyz.com/book/。
HTTP动词,即请求方法(method)
对资源的操作由请求方式决定!
HTTP请求方法 | 资源操作 | 幂等 | 安全 |
GET | 从服务器取出资源(一项或多项) | 是 | 是 |
POST | 在服务器新建一个资源 | 否 | 否 |
PUT | 在服务器更新资源(客户端提供改变后的完整资源) | 是 | 否 |
PATCH | 与PUT类似,用于更新资源,区别在于PATCH代表部分更新 | 否 | 否 |
OPTIONS | 检测服务器所支持的请求方法,响应头中包含一个名为“Allow”的头,值是所支持的方法,如“GET, POST”。 | 是 | 是 |
ELETE | DELETE(删除) | 是 | 否 |
幂等性:对同一REST接口的多次访问,得到的资源状态是相同的。
安全性:对该REST接口访问,不会使服务端资源的状态发生改变。
7.过滤
通过在url上传递参数的形式提交过滤条件。如:
https://api.example.com/v1/zoos?limit=10:指定返回记录的数量
https://api.example.com/v1/zoos?offset=10:指定返回记录的开始位置
https://api.example.com/v1/zoos?page=2&per_page=100:指定第几页,以及每页的记录数
https://api.example.com/v1/zoos?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序
https://api.example.com/v1/zoos?animal_type_id=1:指定筛选条件
HTTP状态码
1xx(信息):通信传输协议级信息
1XX系列响应代码仅在与HTTP服务器沟通时使用,平常极少使用。
2xx(成功):表示客户端的请求已成功接受
200(OK):表示REST API成功执行了客户端请求的任何操作;
201( Created):用户新建资源成功。
202(Accpted):已经接受请求并加入了处理队列,但处理尚未完成。
204(No Content):服务器成功处理,但没有内容可返回。常用于PUT、POST或者DELETE请求的响应。
204响应绝不能包含消息体,因此总是在头字段之后的第一个空行终止。
3xx(重定向 ):表示客户端必须执行一些其他操作才能完成其请求
301(Moved Permanently):请求的URL已永久移走,并设计了新的URL,客户端应该使用新的URL。
REST API应在响应的Location头中指定新的URL,并且将旧的URL请求都定向到新的URL。
302(Found):与301类似,但资源只是临时被移动,客户端应继续使用原有URL。
302 是执行URL重定向的常用方式。
304(Not Modified):如果客户端在发送GET请求时附上if-Modified-Since报头,并且从报头指定版本开始从未修改过该资源,则说明客户端的缓存资源是最新的, 要求客户端使用缓存以节省资源。
此状态代码类似于204,响应正文必须为空。
4xx(客户端错误):此类错误状态代码指向客户端
400(Bad Request):这是一个通用的客户端错误状态,表示客户端请求的语法错误,服务器无法理解。
401(Unauthorized):客户端试图对一个受保护的资源进行操作,却没有提供正确的认证证书(令牌、用户名、密码错误)。
响应必须包含WWW-Authenticate头字段,其中包含适服务器将接受哪种认证。
403(Forbidden):与401错误相对,表明客户端的请求是正确的,但用户没有资源的必要权限。
该响应代码常用于一个资源只允许在特定时间段内访问,或者允许特定IP地址的用户访问的情况。
404(Not Found):服务器无法根据客户端的请求找到资源(网页)。
405(Method Not Allowd):客户端尝试使用资源不允许的HTTP方法。比如,一个资源只支持GET方法,但是客户端使用PUT方法访问。
405响应必须包含Allow标头,该标头列出资源支持的HTTP方法。
406(Not Acceptable):用户请求的格式不可得。比如用户请求JSON格式,但是只有XML格式。
5xx(服务器错误):服务器负责这些错误状态代码
500(Internal Server Error):这是一个通用的服务器错误响应。对于大多数web框架,如果在执行请求处理代码时遇到了异常,它们就发送此响应代码。
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)