REST接口规范---关键点

关于REST

前后端接口按照粗浅的REST规则制定,其主要表现为:

使用GET、POST、PUT、DELETE共4个HTTP Method,而非简单的GET和POST两者。
响应使用HTTP状态码来标志请求的执行结果,而非以往的success字段。
URL符合业界普遍接受的REST规则,减少在URL中标识操作类型的情况,如使用POST /users代替POST /users/save。

出于技术的限制,对于一些特殊的场景,接口会在REST设计的基础之上进行一些妥协,具体参考各接口规范说明。

在REST接口规范中,URL符合以下约束:

实体名称均以复数形式表示,如GET /users或POST /users/status。
URL最后 不得 添加斜杠/符号。
对于GET请求,数据在URL后通过标准的query格式提供,如GET /users?status=1,2&keyword=hello。
对于各系统,可以在URL前统一添加固定的前缀,如GET /api/{entities}/{id},前缀应尽量固定。可以根据请求的类型(如是否需要用户登录授权等)使用不同的前缀。规范推荐按以下规则使用前缀:
    如果是需要登录授权的接口,以/api/js为前缀。
    其它接口,通常没有权限控制,以/api/tool为前缀。

关于数据类型

请求可以使用以下两类数据类型,由具体的项目及接口根据实际情况决定:

表单编码格式。此格式为简单的a=b&c=d这一形式,使用此请求格式时,请求的Content-Type头的值必须为application/x-www-form-urlencoded。
JSON格式。此格式为一个完整的符合JSON格式的串,使用此请求格式时,请求的Content-Type头的值必须为application/json。

响应可以使用以下几类数据类型:

JSON格式。多数接口应当使用JSON格式的响应,此时响应的Content-Type头的值必须为application/json。
HTML格式。部分接口,如文件上传,由于技术的限制必须使用