restFul介绍及其使用规范

什么是REST?

  REST(英文:Representational State Transfer,简称REST)表征状态转移。

restFul规范:
  1、建议使用https作为网络通信协议
  2、接口的url建议加上'api'字符,清晰地表明此url是一个接口
  3、接口版本号相关字符v1/v2/v3...建议加在接口的url上,表明当前接口的版本号
  4、返回值中包含状态码或者Code,状态码标识当前http请求的响应码,响应码具体表明的状态在http协议里已经做了解释。而code则是对请求返回状态的更细的细分,code弥补了状态码不够用的现实,具体的code表明哪种状态,我们需要跟前端商量决定。
    常用状态码:
    200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
    201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
    202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
    204 NO CONTENT - [DELETE]:用户删除数据成功。
    400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
    401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
    403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
    404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
    406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
    410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
    422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
    500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
  5、路径,把网路上的任何东西都看作资源,restful协议建议我们使用名词来表明接口url路径path
    https://www.luffycity.com/api/v1/animals
  6、method:请求方法,restful建议操作同一资源根据不同的http请求方法执行增删改查等不同的操作
    GET:从服务器取出资源
    POST:创建新的资源
    PUT:更新资源的全部属性字段
    PATCH:更新资源的局部属性字段
    DELETE:从服务器上删除资源
  7、过滤筛选,restful建议我们把操作资源时的过滤条件加在url上面,多以查询字符串的方式
    https://www.luffycity.com/api/v1/animals?age=10&gender=0

  8、错误处理,当返回值的状态码为4XX时,返回错误信息,以便前端展示
    return HttpResponse({'detail': '用户名或者密码错误',  status=400})

  9、返回结果,针对不同操作,服务器向用户返回的结果应该符合以下规范(具体是否需要返回须看前端需求)。
    GET/collection:返回资源对象的列表(数组)
    GET/collection/resource:返回单个资源对象
    POST/collection:返回新生成的资源对象
    PUT/collection/resource:返回完整的资源对象
    PATCH/collection/resource:返回完整的资源对象
    DELETE/collection/resource:返回一个空

  10、最好做到Hypermedia,即返回结果中提供链接,连向其他API(url),使得用户不查文档,也知道下一步应该做什么
    {"link": {
      "rel": "collection https://www.example.com/zoos",
      "href": "https://api.example.com/zoos",
      "title": "List of zoos",
      "type": "application/vnd.yourformat+json"
    }}

猜你喜欢

转载自www.cnblogs.com/limaomao/p/9651087.html