RestFul接口设计

1、Rest与RestFul

REST（英文：Representational State Transfer，简称REST），表述性状态转移，指的是一组架构原则。

Restful: 遵守了rest 原则 的web服务或web应用。

2、API设计六要素

资源路径(URI)、HTTP动词(Method)、过滤信息(query-string)、状态码(Status-code)、错误信息(Error)、返回结果(Result)

1）资源路径URI

资源：所有在服务器保存的数据(如:音乐/视频/文章/个人信息…)都是服务器端资源.（项目中资源通常都是指的数据表的一条数据）

URI（Uniform Resource Identifier）：统一资源标志符，包含URL和URN。

URL（Uniform Resource Locator）：统一资源定位符

URN（Uniform Resource Name）：统一资源命名

在HTTP协议中, URI的组成如下

Schema://host[:port]/path[?query-string]

Schema: 使用的协议类型, 如http/https/ftp等

host: 主机域名或IP

port: 端口号(可选)

path: 路径

query-string: 查询参数(可选)

例子:

http://www.tpshop.com/users

https://www.tpshop.com:8080/users?id=100

2）HTTP动词（请求方式）

对于资源, 一般有4个操作, CURD(增/删/改/查)

GET: 从服务器获取资源(一项或多项)

POST: 在服务器新建一个资源

PUT: 在服务器更新资源, 服务器返回完整的属性

DELETE: 从服务器删除资源

3）过滤信息

通常也叫做请求参数或查询字符串。

4）响应状态码

服务端返回的信息, 用来告诉客户端操作结果。

常见状态码：

状态码	含义	说明
200	OK	操作成功, 并返回数据
201	CREATED	新建成功
204	NO CONTENT	删除成功
400	BAD REQUEST	请求语法错误
403	Forbidden	请求没有权限的资源
404	NOT FOUND	没有找到请求的资源

GET

200（OK） - 表示已在响应中发出 
204（无内容） - 资源有空表示 
301（Moved Permanently） - 资源的URI已被更新 
303（See Other） - 其他（如，负载均衡） 
304（not modified）- 资源未更改（缓存） 
400 （bad request）- 指代坏请求（如，参数错误） 
404 （not found）- 资源不存在 
406 （not acceptable）- 服务端不支持所需表示 
500 （internal server error）- 通用错误响应 
503 （Service Unavailable）- 服务端当前无法处理请求

POST

200（OK）- 如果现有资源已被更改 
201（created）- 如果新资源被创建 
202（accepted）- 已接受处理请求但尚未完成（异步处理） 
301（Moved Permanently）- 资源的URI被更新 
303（See Other）- 其他（如，负载均衡） 
400（bad request）- 指代坏请求 
404 （not found）- 资源不存在 
406 （not acceptable）- 服务端不支持所需表示 
409 （conflict）- 通用冲突 
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突） 
415 （unsupported media type）- 接受到的表示不受支持 
500 （internal server error）- 通用错误响应 
503 （Service Unavailable）- 服务当前无法处理请求

PUT

200 （OK）- 如果已存在资源被更改 
201 （created）- 如果新资源被创建 
301（Moved Permanently）- 资源的URI已更改 
303 （See Other）- 其他（如，负载均衡） 
400 （bad request）- 指代坏请求 
404 （not found）- 资源不存在 
406 （not acceptable）- 服务端不支持所需表示 
409 （conflict）- 通用冲突 
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突） 
415 （unsupported media type）- 接受到的表示不受支持 
500 （internal server error）- 通用错误响应 
503 （Service Unavailable）- 服务当前无法处理请求

DELETE

200 （OK）- 资源已被删除 
301 （Moved Permanently）- 资源的URI已更改 
303 （See Other）- 其他，如负载均衡 
400 （bad request）- 指代坏请求 
404 （not found）- 资源不存在 
409 （conflict）- 通用冲突 
500 （internal server error）- 通用错误响应 
503 （Service Unavailable）- 服务端当前无法处理请求

5）错误信息

如果状态码是4xx或者5xx, 需要告诉客户端对应的错误信息. 通常以Json格式返回：

{

“error”: “错误信息”,

}

6）返回结果

针对不同的操作, 服务需要返回的结果应该符合这样的规范

GET /collections — 返回资源列表(数组)

GET /collections/:id — 返回单个资源 eg. /collections/1

POST /collections — 返回新生成的资源

PUT /collections/:id — 返回资源的完整属性

DELETE /collections/:id — 返回204状态码+空文档

实际开发中，通常会将 状态码、错误信息、返回数据，都放到返回结果中。

比如

{"code":200, 'msg':'success', "data":{"id":1,"goods_name":"tp"}}

3、RestFul接口设计风格

TP框架中的资源路由

手册-路由-资源路由、手册-控制器-资源控制器

① 创建api模块

php think build --module api

② 创建news控制器

php think make:controller api/News

③ 设置路由(application/route.php)

\think\Route::resource('news','api/news');

相当于分别设置了以下路由：

\think\Route::get('news','api/news/index');
\think\Route::get('news/create','api/news/create');
\think\Route::post('news','api/news/save');
\think\Route::get('news/:id','api/news/read');
\think\Route::get('news/:id/edit','api/news/edit');
\think\Route::put('news/:id','api/news/update');
\think\Route::delete('news/:id','api/news/delete');

设置后会自动注册7个路由规则，如下：

标识	请求类型	生成路由规则	对应操作方法（默认）
index	GET	news	index
create	GET	news/create	create
save	POST	news	save
read	GET	news/:id	read
edit	GET	news/:id/edit	edit
update	PUT	news/:id	update
delete	DELETE	news/:id	delete

④ 修改News控制器，返回json格式数据

 200, 'msg' => 'success', 'data'=>'index']);
    }

    /**
     * 显示创建资源表单页.
     *
     * @return \think\Response
     */
    public function create()
    {
        return json(['code' => 200, 'msg' => 'success', 'data'=>'create']);
    }

    /**
     * 保存新建的资源
     *
     * @param  \think\Request  $request
     * @return \think\Response
     */
    public function save(Request $request)
    {
        return json(['code' => 200, 'msg' => 'success', 'data'=>'save']);
    }

    /**
     * 显示指定的资源
     *
     * @param  int  $id
     * @return \think\Response
     */
    public function read($id)
    {
        return json(['code' => 200, 'msg' => 'success', 'data'=>'read']);
    }

    /**
     * 显示编辑资源表单页.
     *
     * @param  int  $id
     * @return \think\Response
     */
    public function edit($id)
    {
        return json(['code' => 200, 'msg' => 'success', 'data'=>'edit']);
    }

    /**
     * 保存更新的资源
     *
     * @param  \think\Request  $request
     * @param  int  $id
     * @return \think\Response
     */
    public function update(Request $request, $id)
    {
        return json(['code' => 200, 'msg' => 'success', 'data'=>'update']);
    }

    /**
     * 删除指定资源
     *
     * @param  int  $id
     * @return \think\Response
     */
    public function delete($id)
    {
        return json(['code' => 200, 'msg' => 'success', 'data'=>'delete']);
    }
}

通过postman 分别访问以下七个地址：

请求方式     请求地址
get            http://www.tpshop.com/news
get            http://www.tpshop.com/news/create
post        http://www.tpshop.com/news
get            http://www.tpshop.com/news/33
get            http://www.tpshop.com/news/33/edit
put            http://www.tpshop.com/news/33
delete        http://www.tpshop.com/news/33

4、ajax请求restful接口 

public目录下，创建测试文件 api.html