restful get不传参数404_学习笔记-RESTful基本规范

RESTful简介

上一章节我已经详细的向大家介绍了什么是RESTful，此处就不过多赘述了，详见学习笔记-RESTful简单理解。

REST有主要有两个核心精神：

1. 使用Resource来当做识别的资源，也就是使用一个URL网址来代表一个Resource

2. 同一个Resource则可以有不同的Representations格式变化。这一章的路由实作了Resource概念，而Representation则是用了respond_to方法来实作，稍候我们也会介绍如何使用。

方法介绍

RESTful主要有五大方法，大致情况如下图。

等幂性(Idempotence)

等幂性简单点说就是一次请求和多次请求，资源的状态是一样。比如GET，不论你请求多少次，资源还是在那里。值得注意的是，DELETE ，PUT和PATCH也是等幂的，因为对同一个资源删除一次或者多次，结果是一样的，就是资源被删除了，不存在了。为什么说PUT也是等幂的？当你PUT一个新资源的时候，资源被创建，再次PUT这个URI的时候，资源还是没变。当你PUT一个存在的资源时，更新了资源，再次PUT的时候，还是更新成这个样子。在PUT更新的时候，不能做相对的更新(依赖资源现在的状态)，比如每次对一个数加1，这样资源状态就会变化。应该每次更新成某个数，比如把某个数变成4，则无论多少次PUT，值都是4，这样就是等幂了。我们设计Restful的时候，GET，PATCH, PUT, DELETE一定要设计成等幂的。由于网络是不可靠的，安全性和等幂性就显得特别重要。如果一次请求，服务器收到处理以后，客户端没有收到相应，客户端会再次请求，如果没有等幂性保障，就会发生意想不到的问题。POST是不安全也不等幂的，如果两次POST相同的记录，则会产生两个资源，URI可能是这样/user/record/ 1和/user/record/2，尽管他们的内容是一摸一样的。

安全性

对该REST接口访问，不会使服务器端资源的状态发生改变。

PUT与PATCH：

在上图中，我们看不出PUT与PATCH的区别，但实际上它们是有区别的。简单的说PUT更新时需要传递记录的所有属性，而PATCH只需要传递所对应的属性即可。

例如：有用户记录

{     "user":"张三"     "age":18,     "sex":"男"}

此时，我们要张三的年龄修改为20岁，使用PUT与PATCH方法分别如下。

PUT方法

{    "user":"张三"    "age":20,    "sex":"男"}

PATCH方法

{    "age":20}

路由规范

以用户记录资源为例子: (资源应该使用复数形式)对应的API接口应该如下：

"/api/user/records/" => "record后端接口""/web/user/records/*" => "record界面""/js/user/records/*.js" => "record界面自定义js""/css/user/records/*.css" => "record界面自定义css""/image/user/records/*.*" => "record界面自定义图片资源""/font/user/records/*.*" => "record界面自定义字体资源"

对应的API接口应该如下：

get '/api/user/records' => "获取所有用户记录"post '/api/user/records' => "创建新用户记录"put '/api/user/records/:recordid' => "修改指定ID用户记录"get '/api/user/records/:recordid' => "查看ID用户记录"patch '/api/user/records/:recordid' => "更新指定ID用户记录"delete '/api/user/records/:recordid' => "删除指定ID用户记录"get '/api/user/count/records' => "根据查询条件获取用户记录数量"get '/api/user/limit/records/:pagesize/:pageno' => "根据翻页查找获取用户记录"

批量操作 在请求头部添加: X-Action

post '/api/user/records' => "批量创建新用户记录"patch '/api/user/records' => "批量更新指定用户记录"delete '/api/user/records' => "批量删除指定用户记录"

#实例：

#X-Action: bulk 代表批量操作curl -XDELETE '/api/user/records'  -H 'X-Action: bulk'-d '["id1","id2"]'#X-Action: clean 代表无条件清除curl -XDELETE '/api/user/records' -H 'X-Action: clean'

嵌套 (避免层级过深的URI)

put '/api/records/:recordid/nodes/:nodeid' => "修改指定ID用户记录的指定ID节点信息"get '/api/records/:recordid/nodes' => "查看ID用户记录关联节点信息"patch '/api/records/:recordid/nodes/:nodeid' => "更新指定ID用户记录关联节点信息"delete '/api/records/:recordid/nodes/:nodeid' => "删除指定ID用户记录关联节点信息"

对应界面地址规范

get '/html/user/records/new' => "创建新事件界面"get '/html/user/records/:id/edit' => "编辑事件界面"get '/html/user/records?page=1' => "事件列表界面"get '/html/user/records/:id' => "指定事件ID界面"

请求body规范

一般WEB前端框架中GET/DELETE请求不会携带BODY；操作时需要切记

所有请求参数以json数据格式在请求body里面提交。实例

curl -XGET "http://127.0.0.1/api/events"  -H 'Content-Type: application/json; charset=utf-8' -d '{    "page_size": 1,    "page_num": 10}'

3. 请求头部规范

需要在头部中添加 Content-Type: application/json; charset=utf-8

curl -XGET "http://127.0.0.1/api/events"-H 'Content-Type: application/json; charset=utf-8'-d '{}'

常用返回状态码

200 => "正常请求响应" => "一般响应"

201 => "创建成功请求响应" => "异步用户记录"

202 => "接受" => "异步用户记录"

204 => "资源不存在" => "删除成功返回||请求资源不存在"

301 => "跳转" => "界面跳转"

302 => "临时跳转" => "界面跳转"

400 => "异常请求" => "请求参数异常"

401 => "认证失败" => "未登录操作资源"

403 => "禁止访问" => "紧张访问资源"

具体返回码细节

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)- 服务端当前无法处理请求

本文的初衷为学习笔记的分享，部分图文来源于网络，如侵，联删。