2019-11-20

Rest API 个人学习

本文总阅读量次

内容目录

  • API Root URL
  • EndPoints
  • HTTP动词
  • Response
    • 200 ok
    • 201 Created
    • 202 Accepted
    • 204 No Content
    • 400 Bad Request
    • 401 Unauthorized
    • 403 Forbidden
    • 404 Not Found
    • 408 Request Timeout
    • 429 Too Many Request
  • 参考

    API Root URL

    API 的根入口点应尽可能保持足够简单，这里有两个常见的 URL 根例子：
  • api.example.com/*
  • example.com/api/*

    如果你的应用很庞大或者你预计它将会变的很庞大，那 应该 将 API 放到子域下（api.example.com）。这种做法可以保持某些规模化上的灵活性。

    EndPoints

    端点就是指向特定资源或资源集合的 URL。在端点的设计中，必须 遵守下列约定：
  • URL 的命名全部小写
  • URL 中资源（resource）的命名是名词复数形式
  • 优先使用Restful类型的URL
  • URL必须是易读的
  • URL不可暴露服务器架构

Example

  • https://api.example.com/zoos
  • https://api.example.com/animals
  • https://api.example.com/zoos/{zoo}/animals

    HTTP动词

    对于资源的具体操作类型，由 HTTP 动词表示。常用的 HTTP 动词有下面五个（括号里是对应的 SQL 命令）。
  • GET（SELECT）：从服务器取出资源（一项或多项）。
  • POST（CREATE）：在服务器新建一个资源。
  • PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  • PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  • DELETE（DELETE）：从服务器删除资源。

    Response

    只有来自客户端的请求被正确的处理后才能返回 2xx 的响应，所以当 API返回 2xx 类型的状态码时，前端认定该请求已处理成功。
    常见返回错误消息的方法：
  • 将错误信息放入HTTP响应首部
1
2
3
X-MYNAME-ERROR-CODE: 4001
X-MYNAME-ERROR-MESSAGE: Bad authentication token
X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication
  • 直接放入响应实体中
1
2
3
4
5
6
7
8
9
HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:02:59 GMT
Connection: keep-alive

{"error_code":40100,"message":"Unauthorized"}

200 ok

200 状态码是最常见的 HTTP 状态码，在所有成功的 GET 请求中，返回此状态码。HTTP 响应实体部分就是数据

1
2
3
4
5
{
    "id": 1,
    "username": "godruoyi",
    "age": 88,
}

201 Created

当服务器创建数据成功时，返回此状态码。常见的应用场景是使用 POST 提交用户信息，如：

  • 添加了新用户
  • 上传了图片
  • 创建了新活动
    等，都可以返回 201 状态码。可以选择在用户创建成功后返回新用户的数据

202 Accepted

该状态码表示服务器已经接受到了来自客户端的请求，但还未开始处理。常用短信发送、邮件通知、模板消息推送等这类很耗时需要队列支持的场景中；
返回该状态码时，响应实体为空。

204 No Content

该状态码表示响应实体不包含任何数据，其中：

  • 在使用 DELETE 方法删除资源成功时，返回该状态码
  • 使用 PUT、PATCH 方法更新数据成功时,返回此状态码

    400 Bad Request

    由于明显的客户端错误（例如，请求语法格式错误、无效的请求、无效的签名等），服务器应该放弃该请求。
    当服务器无法从其他 4xx 类型的状态码中找出合适的来表示错误类型时,返回该状态码。

    401 Unauthorized

    该状态码表示当前请求需要身份认证，例如
  • 未认证用户访问需要认证的 API
  • access_token 无效/过期
    客户端在收到 401 响应后，提示用户进行下一步的登录操作。

    403 Forbidden

    该状态码可以简单的理解为没有权限访问该请求，服务器收到请求但拒绝提供服务。
    如当普通用户请求操作管理员用户时，返回该状态码。
    1
    2
    3
    4
    5
    6
    7
    8
    HTTP/1.1 403 Forbidden
    Server: nginx/1.11.9
    Content-Type: application/json
    Transfer-Encoding: chunked
    Cache-Control: no-cache, private
    Date: Sun, 24 Jun 2018 13:05:34 GMT
    Connection: keep-alive
    {"error_code":40301,"message":"权限不足"}

404 Not Found

该状态码表示用户请求的资源不存在

  • 获取不存在的用户信息 (get /users/9999999）
  • 访问不存在的端点

408 Request Timeout

客户端请求超时时返回该状态码，需要注意的时，该状态码表示客户端请求超时，而不是在涉及第三方 API 调用超时时

429 Too Many Requests

该状态码表示用户请求次数超过允许范围。如 API设定为 60次/分钟，当用户在一分钟内请求次数超过 60 次后回该状态码。并且在响应首部中加上下列头部：

1
2
3
4
X-RateLimit-Limit: 10 请求速率（由应用设定，其单位一般为小时/分钟等，这里是 10次/5分钟）  
X-RateLimit-Remaining: 0 当前剩余的请求数量
X-RateLimit-Reset: 1529839462 重置时间
Retry-After: 120 下一次访问应该等待的时间（秒）
1
2
3
4
5
6
7
8
9
10
11
12
13
HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1529839462
Retry-After: 290
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 11:19:32 GMT
Connection: keep-alive

{"message":"You have exceeded your rate limit.","error_code":42900}

参考链接

Rica Zhang

Rica Zhang

Hello, World!