URI格式规范
URI中尽可能使用连字符”-“代替下划线”_”的使用
URI中统一使用小写字母
URI中不要包含文件(脚本)的扩展名git
URI命名规范
文档(Document)类型的资源用名词(短语)单数命名
集合(Collection)类型的资源用名词(短语)复数命名
仓库(Store)类型的资源用名词(短语)复数命名
控制器(Controller)类型的资源用动词(短语)命名
URI中有些字段能够是变量，在实际使用中能够按需替换
CRUD的操做不要体如今URI中，HTTP协议中的操做符已经对CRUD作了映射。github
HTTP请求方法的使用
GET方法用来获取资源
PUT方法可用来新增/更新Store类型的资源
PUT方法可用来更新一个资源的所有属性，使用时传递全部属性的值，即便有的值没有改变
PATCH方法更新资源的部分属性。由于 PATCH 比较新，并且规范比较复杂，因此真正实现的比较少，通常都是用 POST 替代
POST方法可用来建立一个资源
POST方法可用来触发执行一个Controller类型资源
DELETE方法用于删除资源json
HTTP响应状态码的使用
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”) 客户所支持的数据类型，服务端没法知足
429 (“Too Many Requests”) 客户端在规定的时间里发送了太多请求，在进行限流的时候会用到
500 (“Internal Server Error”) 服务器端的接口错误，此错误于客户端无关api
HTTP Headers
Content-Type 标示body的数据格式
Content-Length body 数据体的大小，客户端能够根据此标示检验读取到的数据是否完整，也能够经过Header判断是否须要下载可能较大的数据体
Last-Modified 用于服务器端的响应，是一个资源最后被修改的时间戳，客户端(缓存)能够根据此信息判断是否须要从新获取该资源
ETag 服务器端资源版本的标示，客户端(缓存)能够根据此信息判断是否须要从新获取该资源，须要注意的是，ETag若是经过服务器随机生成，可能会存在多个主机对同一个资源产生不一样ETag的问题
Store类型的资源要支持有条件的PUT请求
Location 在响应header中使用，通常为客户端感兴趣的资源URI,例如在成功建立一个资源后，咱们能够把新的资源URI放在Location中，若是是一个异步建立资源的请求，接口在响应202 (“Accepted”)的同时能够给予客户端一个异步状态查询的地址
Cache-Control, Expires, Date 经过缓存机制提高接口响应性能,同时根据实际须要也能够禁止
客户端对接口请求作缓存。对于REST接口来讲，若是某些接口实时性要求不高的状况下，咱们可使
用max-age来指定一个小的缓存时间，这样对客户端和服务器端双方都是有利的。通常来讲只对GET
方法且返回200的状况下使用缓存，在某些状况下咱们也能够对返回3xx或者4xx的状况下作缓存，能够防范错误访问带来的负载。
咱们能够自定义一些头信息，做为客户端和服务器间的通讯使用，但不能改变HTTP方法的性质。自
定义头尽可能简单明了，不要用body中的信息对其做补充说明。缓存
API 地址和版本
在 url 中指定 API 的版本是个很好地作法。若是 API 变化比较大，能够把 API 设计为子域名，好比 https://api.github.com/v3；也能够简单地把版本放在路径中，好比 https://example.com/api/v1。另外一种作法是，将版本号放在HTTP头信息中。服务器