RESTful API 设计规范

一个架构符合REST(REpresentational State Transfer)原则,就称它为RESTful架构。

资源 (Resources)

URI (Uniform Resource Identifiers) 统一资源标示符

URI = scheme “://” authority “/” path [ “?” query ] [ “#” fragment ]

URI规范:

  • URI不包含动词,使用名词复数。
  • URI不使用大写。
  • URI层级不要太深。

URL(Uniform Resource Locator) 统一资源定位符(URI的实现)

对于REST API来说一个资源对应一个唯一的URI(URL)

表现(Representation)

HTTP请求的头信息中,用Accept和Content-Type标示。

状态转化(State Transfer)

  • GET:获取资源
    GET /zoos
    GET /zoos/1
    GET /zoos/1/employees
    GET /zoos/1/employeessortby=name&order=asc

  • POST:新建资源(也可以更新资源)
    POST /animals 新增动物
    POST /zoos/1/employees 新增动物园1雇员

  • PUT:更新单个资源 全量更新
    PUT /animals/1
    PUT /zoos/1

  • DELETE:删除资源
    DELETE /zoos/1/animals //删除id为1的动物园内的所有动物

常见异常返回码

  • 400 bad request 常用在参数校验
  • 401 unauthorized 未经验证的用户,常见于未登录。如果经过验证后依然没权限,应该 403(即 authentication 和 authorization 的区别)。
  • 403 forbidden 无权限
  • 404 not found 资源不存在
  • 500 internal server error 代码逻辑错误导致,比如数据库连接失败、空指针异常、除0错误

异步任务

由于互联网通信 高延时(high latency)、高并发等特点 异步任务派上大用场。

  1. 先返回任务创建成功
  2. 客户端轮询任务状态

规范是提高效率的利器

    原文作者:清醒的cola
    原文地址: https://www.jianshu.com/p/82679dffbd04
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞