抽象地说,任何一个请求都可以看作对资源的操作。
简单地说,restful的风格是面向资源的请求方式。
URI(Uniform Resource Identifiers) 统一资源标示符
URL(Uniform Resource Locator) 统一资源定位符
URL是URI的具体实现,对于REST API来说一个资源一般对应一个唯一的URI(URL)。
URI的格式定义如下:
scheme://host/pathname?query#fragment
- "/"分隔符一般用来对资源层级的划分
如:jianshu.com/accounts/zh-cn
- pathname部分全部使用小写,query部分可以使用大小驼峰命名
如:jianshu.com/accounts?page=1&pageSize=10
- pathname同级资源单词分隔符尽量使用"-"符号
如: jianshu.com/wn-location/zh-cn
-
pathname部分不使用.html等后缀名
-
pathname部分不使用动词,如用transaction替代transact,资源动作用method表示。
错误示例:
DELETE jianshu.com/deleteuser/1
建议使用:
DELETE jianshu.com/user/1
- 严格来说,根据查询条件找不到结果时,要返回404的状态码,但避免前端解析复杂或混淆,一般可以直接返回空数组。
rest请求常用method
GET PUT POST DELETE不作更多解释,表示对资源的获取,修改,新建,删除。据RFC2616标准,还有其他5种方法:PATCH、OPTIONS、HEAD、TRACE和CONNECT。其中后三者很少使用。
1. PATCH
PATCH 用于资源的部分内容的更新,
例如更新某一个字段。具体比如说只更新用户信息的电话号码字段。
而 PUT 用于更新某个资源较完整的内容,
比如说用户要重填完整表单更新所有信息,后台处理更新时甚至可能只是保留内部记录 ID 不变。
2. OPTIONS
OPTIONS的主要用途有两个:
1)获取服务器支持的HTTP请求方法,也是黑客经常使用的方法。
2)用来检查服务器的性能。
例如:AJAX进行跨域请求时的预检,需要向另外一个域名的资源发送一个HTTP OPTIONS请求头,用以判断实际发送的请求是否安全。
HTTP响应状态码的使用
200 (“OK”) 用于一般性的成功返回
200 (“OK”) 不可用于请求错误返回
201 (“Created”) 资源被创建
202 (“Accepted”) 用于Controller控制类资源异步处理的返回,仅表示请求已经收到。对于耗时比较久的处理,一般用异步处理来完成
204 (“No Content”) 此状态可能会出现在PUT、POST、DELETE的请求中,一般表示资源存在,但消息体中不会返回任何资源相关的状态或信息。
301 (“Moved Permanently”) 资源的URI被转移,需要使用新的URI访问
302 (“Found”) 不推荐使用,此代码在HTTP1.1协议中被303/307替代。我们目前对302的使用和最初HTTP1.0定义的语意是有出入的,应该只有在GET/HEAD方法下,客户端才能根据Location执行自动跳转,而我们目前的客户端基本上是不会判断原请求方法的,无条件的执行临时重定向
303 (“See Other”) 返回一个资源地址URI的引用,但不强制要求客户端获取该地址的状态(访问该地址)
304 (“Not Modified”) 有一些类似于204状态,服务器端的资源与客户端最近访问的资源版本一致,并无修改,不返回资源消息体。可以用来降低服务端的压力
307 (“Temporary Redirect”) 目前URI不能提供当前请求的服务,临时性重定向到另外一个URI。在HTTP1.1中307是用来替代早期HTTP1.0中使用不当的302
400 (“Bad Request”) 用于客户端一般性错误返回, 在其它4xx错误以外的错误,也可以使用400,具体错误信息可以放在body中
401 (“Unauthorized”) 在访问一个需要验证的资源时,验证错误
403 (“Forbidden”) 一般用于非验证性资源访问被禁止,例如对于某些客户端只开放部分API的访问权限,而另外一些API可能无法访问时,可以给予403状态
404 (“Not Found”) 找不到URI对应的资源
405 (“Method Not Allowed”) HTTP的方法不支持,例如某些只读资源,可能不支持POST/DELETE。但405的响应header中必须声明该URI所支持的方法
406 (“Not Acceptable”) 客户端所请求的资源数据格式类型不被支持,例如客户端请求数据格式为application/xml,但服务器端只支持application/json
409 (“Conflict”) 资源状态冲突,例如客户端尝试删除一个非空的Store资源
412 (“Precondition Failed”) 用于有条件的操作不被满足时
415 (“Unsupported Media Type”) 客户所支持的数据类型,服务端无法满足
500 (“Internal Server Error”) 服务器端的接口错误,此错误于客户端无关
网友评论