RESTful 规范

Posted shiwei1930

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了RESTful 规范相关的知识,希望对你有一定的参考价值。

一. 什么是RESTful

  • REST与技术无关,代表的是一种软件架构风格,REST是Representational State Transfer的简称,中文翻译为“表征状态转移”
  • REST从资源的角度类审视整个网络,它将分布在网络中某个节点的资源通过URL进行标识,客户端应用通过URL来获取资源的表征,获得这些表征致使这些应用转变状态
  • REST与技术无关,代表的是一种软件架构风格,REST是Representational State Transfer的简称,中文翻译为“表征状态转移”
  • 所有的数据,不过是通过网络获取的还是操作(增删改查)的数据,都是资源,将一切数据视为资源是REST区别与其他架构风格的最本质属性
  • 对于REST这种面向资源的架构风格,有人提出一种全新的结构理念,即:面向资源架构(ROA:Resource Oriented Architecture)

web接口

# 请求工具:postman => https://www.getpostman.com/

# 接口:url链接,通过向链接发生不同的类型请求与数据得到相应的响应数据

二.RESTful API设计

  1. https 通常使用https协议 链接一 链接二请求

  2. 域名: 有api关键字出现

        -- https://api.example.com  (存在跨域问题)
        -- https://example.com/api
  3. 版本: 不同版本需要标注

        -- https://example.com/api/v1 | -- https://example.com/api/1
        -- https://example.com/api/v2 | -- https://example.com/api/2
        -- 另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观
  4. 请求方法: 不同的方法代表不同的操作,从请求方式上决定操作

        GET      :从服务器取出资源(一项或多项)
        POST     :在服务器新建一个资源
        PUT      :在服务器更新资源(客户端提供改变后的完整资源)
        PATCH    :在服务器更新资源(客户端提供改变的属性)
        DELETE   :从服务器删除资源
  5. 资源过滤 通过接口传递参数(锚参)来过滤资源

        -- ?limit=10:              指定返回记录的数量
        -- ?offset=10:             指定返回记录的开始位置
        -- ?page=2&per_page=100:   指定第几页,以及每页的记录数
        -- ?sortby=name&order=asc: 指定返回结果按照哪个属性排序,以及排序顺序
        -- ?animal_type_id=1:      指定筛选条件
  6. 资源路径 请求的目标数据称之为资源,资源一般都有名词复数表示

    路径又称"终点"(endpoint),表示API的具体网址

    在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,

    而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),

    所以API中的名词也应该使用复数

       -- https://example.com/api/v1/books  (之前不规范的案例: /get_books/)
  7. 状态码 返回数据要标准状态码,通过在数据中 {"status": 200}

            200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
            201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
            202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
            204 NO CONTENT - [DELETE]:用户删除数据成功。
            400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
            401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
            403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
            404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
            406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
            410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
            422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
            500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
  8. 错误处理 请求失败需要标注错误信息

    {
        "message": "请求参数不合法",
    }
  9. 操作结果 针对不同操作,服务器向用户返回的结果应该符合以下规范

    GET /collection:            返回资源对象的列表(数组)
    GET /collection/resource:   返回单个资源对象
    POST /collection:           返回新生成的资源对象
    PUT /collection/resource:   返回完整的资源对象
    PATCH /collection/resource: 返回完整的资源对象
    DELETE /collection/resource:返回一个空文档
  10. 子资源返回资源接口 返回结果中如果有子资源,返回子资源的链接地址

    RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么

    {"link": {
      "rel":   "collection https://www.example.com/zoos",
      "href":  "https://api.example.com/zoos",
      "title": "List of zoos",
      "type":  "application/vnd.yourformat+json"
    }}

上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。

    rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),=
    href表示API的路径,
    title表示API的标题,
    type表示返回类型。

Hypermedia API的设计被称为HATEOAS

Github的API就是这种设计,访问api.github.com会得到一个所有可用API的网址列表。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}

从上面可以看到,如果想获取当前用户的信息,应该去访问api.github.com/user,然后就得到了下面结果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3/users/#get-the-authenticated-user",
}

上面代码表示,服务器给出了提示信息,以及文档的网址。

三. 其他

  • API的身份认证应该使用OAuth 2.0框架
  • 服务器返回的数据格式,应该尽量使用JSON,避免使用XML

参考文章 理解RESTful架构

以上是关于RESTful 规范的主要内容,如果未能解决你的问题,请参考以下文章

restful 架构风格的curd(增删改查)

php Yoast SEO规范输出的代码片段

php Yoast SEO规范输出的代码片段

RESTful规范

Restful规范

RESTful规范