RESTful基本要求

文章目录

RESTful -Representational State Transfer

1 什么是RESTful

  • 资源 （Resources）

    网络上的一个实体，或者说是网络上的一个具体信息，并且每个资源都有一个独一无二得URI与之对应；获取资源-直接访问URI即可

  • 表现层（Representation）

    如何去表现资源 - 即资源得表现形式；如HTML , xml , JPG , json等

  • 状态转化（State Transfer）

    访问一个URI即发生了一次 客户端和服务端的交互；此次交互将会涉及到数据和状态得变化

    客户端需要通过某些方式触发具体的变化 - HTTP method 如 GET， POST，PUT，PATCH，DELETE 等

2 RESTful的特征

  • 每一个URI代表一种资源

  • 客户端和服务器端之前传递着资源的某种表现

  • 客户端通过HTTP的几个动作 对 资源进行操作 - 发生‘状态转化’

3 如何设计符合RESTful 特征的API

  • 协议 - http/https

  • 域名

    域名中体现出api字样，如

    https://api.example.com

    or

    https://example.org/api/

  • 版本:

    https://api.example.com/v1/

  • 路径 -

    路径中避免使用动词，资源用名词表示，案例如下

    https://api.example.com/v1/users
https://api.example.com/v1/animals

  • HTTP动词语义

    请求动词说明
    GET（SELECT）从服务器取出资源（一项或多项）
    POST（CREATE）在服务器新建一个资源
    PUT（UPDATE）在服务器更新资源
    DELETE（DELETE）从服务器删除资源

    具体案例如下：

    请求动作请求资源说明
    GET/zoos列出所有动物园
    POST/zoos新建一个动物园
    GET/zoos/ID获取某个指定动物园的信息
    PUT/zoos/ID更新某个指定动物园的信息
    DELETE/zoos/ID删除某个动物园
    GET/zoos/ID/animals列出某个指定动物园的所有动物
    DELETE/zoos/ID/animals/ID删除某个指定动物园的指定动物

  • 巧用查询字符串

    ?type_id=1：指定筛选条件
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。

  • 状态码

    用HTTP响应码表达 此次请求结果，例如

    响应码说明
    200 OK - [GET]服务器成功返回用户请求的数据
    404 NOT FOUND用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
    500 INTERNAL SERVER ERROR服务器发生错误