RESTful API介绍

RESTful API介绍

什么是 RESTFul API

REST 的全称是 Representational State Transfer——表象层状态转变

  1. 每一个 URL 代表一种资源
  2. 客户端和服务器之间,传递资源的某种表现层
  3. 客户端通过 http 请求类型(get, post, put, delete 等),对服务器资源进行操作

RESTFul API 六大原则

  1. C-S 架构

    Client-Server 架构,数据的存储在 Server 端,Client 端只需使用就行。

  2. 无状态

    客户端的每一次请求带有充分的信息能够让服务端识别,服务端能够根据请求的各种参数,无需保存客户端的状态,将响应正确返回给客户端。

  3. 统一接口

    REST 接口约束定义为:

    • 资源识别
    • 请求动作
    • 响应信息
    它表示通过
    

    uri 标出你要操作的资源,通过请求动作(http method)标识要执行的操作,通过返回的状态码来表示这次请求的执行结果。

  4. 一致的数据格式

    服务端返回 XML 或者 JSON 格式数据。

  5. 可缓存

    客户端可以缓存页面的响应内容。

  6. 按需编码、可定制代码

    服务端可选择临时给客户端下发一些功能代码让客户端来执行,从而定制和扩展客户端的某些功能。

RESTFul API 最佳示例

  • 版本控制

    在 url 后面加上 v1, v2, v3 表示版本号

    http://example.com/api/v2
    
  • 参数命名规范

    query parameter 可以采用驼峰命名法,也可以采用下划线命名的方式。

    http://example.com/api/users/today_login //获取今天登陆的用户
    http://example.com/api/users/today_login&sort=login_desc //获取今天登陆的用户、登陆时间降序排列
    
  • url 命名规范

    在 RESTFul 架构中,每个 url 代表一种资源,所以 url 中不能有动词只能有名词,并且名词中也应该使用复数。实现者应使用相应的 Http 动词 GET、POST、PUT、PATCH、DELETE、HEAD 来操作这些资源即可。

    不规范的 url:

    http://example.com/api/getAllUsers		  //GET 获取所有用户
    http://example.com/api/getUser/1          //GET 获取 id 为 1 用户信息
    http://example.com/api/updateUser/1       //POST 更新标识为 1 用户信息
    

    规范的 RESTFul 风格的 url:

    http://example.com/api/users              //GET 获取所有用户信息
    http://example.com/api/users/1            //GET 获取 id 为 1 用户信息
    http://example.com/api/users              //POST 添加新的用户
    http://example.com/api/users/1            //PUT 更新 id 为 1 用户信息
    http://example.com/api/users/1            //DELETE 删除 id 为 1 用户信息
    
  • 统一返回数据格式

    对于合法的请求应该返回统一的数据格式。

    • code——包含一个整数类型的 HTTP 响应状态码。
    • status——包含文本:”success”,”fail” 或 ”error”。HTTP 状态响应码在 500 - 599 之间为 ”fail”,在 400 - 499 之间为 ”error”,其它均为 ”success”(例如:响应状态码为 1XX、2XX 和 3XX)。这个根据实际情况其实是可要可不要的。
    • message——当状态值为 ”fail” 和 ”error” 时有效,用于显示错误信息。参照国际化(il8n)标准,它可以包含信息号或者编码,可以只包含其中一个,或者同时包含并用分隔符隔开。
    • data——包含响应数据。当状态值为 ”fail” 或 ”error” 时,data 仅包含错误原因或异常名称、或者 null 也是可以的。

    例如,返回成功响应的 JSON 格式数据:

    {
      "code": 200,
      "message": "success",
      "data": {
        "userName": "zhangsan",
        "age": 18,
        "address": "shanghai"
      }
    }
    

    返回失败的响应 JSON 格式:

    {
      "code": 401,
      "message": "error message",
      "data": null
    }
    
  • 合理使用 query parameter

    在请求数据时,客户端经常会对数据进行过滤和分页等要求,而这些参数推荐采用 HTTP Query Parameter 的方式实现。

    //获取第一页且关键词包含王的用户
    http://example.com/api/users?page=1&key=王
    

HTTP 状态码

  • 总体分类
    • 1xx:指示信息——表示请求已接收,继续处理
    • 2xx:成功——表示请求已经被成功接收并处理
    • 3xx:重定向——完成请求需要进一步处理(跳转)
    • 4xx:客户端错误——请求有错误或者请求无法实现
    • 5xx:服务器端错误——服务器端未能实现合法请求
  • 常见 http 状态码
    • 200 OK:正常返回信息(请求被成功处理)
    • 301 Permanently Moved:永久重定向
    • 302 Temporarily Moved:临时重定向
    • 400 Bad Request:客户端请求有错误
    • 401 Unauthorized:请求未授权
    • 403 Forbidden:服务器收到请求,但拒绝提供服务
    • 404 Not Found:请求资源不存在
    • 500 Internal Server Error:服务器内部错误
    • 503 Server Unavailable:服务器当前无法处理请求,一段时间后可能恢复

Copyright: 采用 知识共享署名4.0 国际许可协议进行许可

Links: https://cangmang.xyz/articles/1642847807716