RESTful API 设计规范

2024年2月4日 165次阅读 来源: 清醒的cola

一个架构符合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
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞