RESTful API接口基本内容
RESTful API接口基本内容
目录
RESTful API接口基本内容
一、RESTful是什么？
1.1.基本特点
1.2.设计概念和准则
1.3.http协议
二、RESTful与SOAP WebService 架构有什么区别？
2.1.WebService 架构概念
2.2.两者对比
三、如何实现符合RESTful规范的API？
3.1.资源路径（URI）
3.2.HTTP动词-请求
3.3.过滤信息
3.4.HTTP状态码-响应
3.5.错误处理
3.6.返回结果
四、开发环境搭建(不看)
五、使用RESTful，前后端分离之：前端
第一种方式：通过定义本地json文件(淘汰)
第二种方式：第三方的工具
第三种方式：json-server(推荐)
一、RESTful是什么？
1.1.基本特点
本质核心：一种软件架构
风格：面向资源
解决的问题：降低开发的复杂性、提高系统的可伸缩性
1.2.设计概念和准则
(1).网络上的所有事物都可以被抽象为资源(网络上的一个实体或者一个具体信息)。
(2).每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识。
(3).restful是基于http协议实现的。
1.3.http协议
HTTP是一个属于应用层的协议，特点是简捷、快速，结构如下：
schema://host[：port]/path[？query-stringl][#anchor]
- scheme：指定低层使用的协议（例如：http，https，ftp）
- host：服务器的IP地址或者域名
- port：服务器端口，默认为80,https默认端口为443
- path：访问资源的路径
- query-string：发送给htp服务器的数据
- anchor：锚
二、RESTful与SOAP WebService 架构有什么区别？
2.1.WebService 架构概念
WebService是一种跨编程语言和跨操作系统平台的远程调用技术。
WebService通过HTTP协议发送请求和接收结果时采用XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和XML内容格式就是SOAP协议。
2.2.两者对比
(1)效率和易用性
SOAP由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。
RESTful由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了Http最初的应用协议设计理念。
(2)安全性
RESTful对于资源型服务接口来说很合适，同时特别适合对于效率要求很高，但是对于安全要求不高的场景。(适用于安全性不高，运行效率高的接口)
SOAP的成熟性可以给需要提供给多开发语言的，对于安全性要求较高的接口设计带来便利。所以我觉得纯粹说什么设计模式将会占据主导地位没有什么意义，关键还是看应用场景。(适用于安全性高的接口，但是运行效率有所下降)
三、如何实现符合RESTful规范的API？
3.1.资源路径（URI）
在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该使用复数。
举例
举例来说，有一个API提供动物园（Z00）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
https(安全性更高)://api.example.com/v1(留空作为版本号)/zoos //动物园资源
https://api.example.com/v1/animals //动物资源
https://api.example.com/v1/animals/(动物id) //对应哪个动物
https://api.example.com/v1/employees/(人员id) //雇员资源
3.2.HTTP动词-请求
对于资源的操作（CURD），由HTTP动词（谓词）表示。
GET：从服务器取出资源（一项或多项）。
POST：在服务器新建一个资源。
PUT：在服务器更新资源（客户端提供改变后返回改变后完整资源 例如当修改密码时，输入用户id和密码，则修改成功时服务端会返回用户id和密码）
PATCH：在服务器更新资源（客户端仅返回改变的属性 例如当修改密码时，输入用户id和密码，则修改成功时服务端只会返回密码）。
DELETE：从服务器删除资源。
举例
POST/zoos：新建一个动物园
GET/zoos/ID：获取某个指定动物园的信息
PUT/zooS/ID：更新某个指定动物园的信息
DELETE/zood/ID：删除某个动物园
3.3.过滤信息
如果记录数量很多，服务器不可能都将它们返回给用户。
API应该提供参数，过滤返回结果，即通过增加参数来过滤。
举例
？offset=10：指定返回记录的开始位置。
？page=2&per_page=100：指定第几页，以及每页的记录数。
？sortby=name&order=asc：指定返回结果排序，以及排序顺序。
？animal_type_id=1：指定筛选条件
3.4.HTTP状态码-响应
服务器向用户返回的状态码和提示信息，使用标准HTTP状态码。
200OK：服务器成功返回用户请求的数据(get)，该操作是幂等的。(查)
201CREATED：新建或修改数据成功(post put path)。(增、改)
204NO CONTENT：删除数据成功(delete)。(删)
400BAD REQUEST：语义有误，当前请求无法被服务器理解、请求参数有误
401 Unauthorized ：请求语法正确但是用户没有认证，无法进行当前操作。(无认证、无权限)
403 Forbidden ：(用户提供了认证参数，但是参数错误、权限不足)表示服务器拒绝请求，用户访问是被禁止的。
404Not Found：请求资源不存在
422 Unprocesable Entity： (新建的用户的属性有遗漏、或格式错误)当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR： 服务器发生错误，用户将无法判断发出的请求是否成功。
3.5.错误处理
错误处理
如果状态码是4xx或者5xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可
{
"error"：“参数错误” 500的服务器参数就不可暴露
}
3.6.返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范：
GET/collections：返回资源对象的列表（数组）
GET/collections/identity：返回单个资源对象
POST/collections：返回新生成的资源对象
PUT/collections/identity：返回完整的资源对象
PATCH/collections/identity：返回被修改的属性
DELETE/collections/identity：(204)返回一个空文档
四、开发环境搭建(不看)
下载UPUPW.NET集成环境
http://www.upupw.net/
右键，以管理员身份运行
之后输入1，创建一个虚拟主机
回车、回车、n不查看，创建成功：
并且删除该目录下的所有文件
添加虚拟主机，以及取消跨站目录限制
编辑httpd-vhosts.conf文件
注释php
按q回到主页面
输入rr重启
添加虚拟主机的本地hosts解析b
以管理员身份 编辑
差看是否成功
刷新页面
成功搭建本地的开发环境
五、使用RESTful，前后端分离之：前端
第一种方式：通过定义本地json文件(淘汰)
1.前后端事先约定好接口的数据返回标准（契约精神）
2.后端开始开发接口
3.前端通过假数据的方式模拟一个后端接口
实例：
user.json数据如下：
执行代码如下：
Document
执行结果如下：
缺陷：
无法进行post请求、路径是写死的，后求修改量太大、书写模拟文件也十分麻烦
第二种方式：第三方的工具
mock.js：对你请求的Ajax请求进行拦截，并且生成随机数据，返回结果
实例代码如下：
Document
第三种方式：json-server(推荐)
json-server
https://github.com/typicode/json-server
http:/jsonplaceholder.typicode.com/
地址即资源的思想：
http://api.demo.com/users： 应该是所有的用户数据
http://api.demo.com/products：所有的产品数据
http://api.demo.com/products/iphone： 特指iphone这个商品
实例：
使用步骤:
1.安装json-servernpm install -g json-server
2.产看是否安装成功
cmd中输入：json-server -version
0.15.0
如果无该命令，请确定你的npm,cnpm环境变量是否添加正确
3.监听文件
1.进入.json文件的目录下
.json文件的格式如下：
{
"posts"(是一个url链接资源): [
(资源){ "id": 1, "title": "json-server", "author": "typicode" }
],
"comments": [
{ "id": 1, "body": "some comment", "postId": 1 }
],
"profile": { "name": "typicode" }
}
2.输入json-server --watch data.json 即可对该文件数据实现监听
4.会自动开启本地的web服务，你在网页中对Resources进行请求即可
5.执行结果如下：
