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://www.cangmangai.cn/archives/introduce-restful-api

Buy me a cup of coffee ☕.