RESTful API介绍

一  什么是RESTful

REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为“表征状态转移”或“表现层状态转化”。

二  RESTful API 设计

• API与用户通信协议,总是使用HTTPS协议:https总是比http安全

• 域名

  • https://api.example.com  尽量将API部署在专用域名（会存在跨域问题）
  • https://example.org/api/  API很简单
  • 例如写一个查询所有图书的api接口:https://api.example.com/books

• 版本:每个接口都应该有版本

  • URL，如：https://api.example.com/v1/ https://127.0.0.1/api/v2/books(推荐用这种)
    请求头 跨域时，引发发送多次请求

• 路径，视网络上任何东西都是资源，均使用名词表示（可复数）

  • https://api.example.com/v1/books
    https://api.example.com/v1/animals
    https://api.example.com/v1/employees

  • 不能这么写:

    • 获取所有图书:https://127.0.0.1/api/get_all_books

    • 新增一本书:https://127.0.0.1/api/add_book

  • 统一都用这个:https://api.example.com/v1/books

• method

  • GET ：从服务器取出资源（一项或多项）
    POST ：在服务器新建一个资源
    PUT ：在服务器更新资源（客户端提供改变后的完整资源）
    PATCH ：在服务器更新资源（客户端提供改变的属性）
    DELETE ：从服务器删除资源

• 过滤，通过在url上传参的形式传递搜索条件

  • https://api.example.com/v1/zoos?limit=10：指定返回记录的数量

• 状态码

  • 请求回去,需要有状态码
    自定义状态码
    status:

    • 100表示成功
      101表示用户名密码错误
      102我也不知道什么错误
      
      

• 错误处理，应返回错误信息，error当做key。

  • {status:100,error:'错误信息写上'}

• 返回结果，针对不同操作，服务器向用户返回的结果应该符合以下规范。

  • GET /books：返回资源对象的列表（数组）
    GET /books/1：返回单个资源对象
    POST /books：返回新生成的资源对象 -新增,传数据,一旦新增完成,把新的资源对象返回
    PUT /books/1：返回完整的资源对象
    PATCH /books/1：返回完整的资源对象
    DELETE /books/1：返回一个空文档

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

  • {
    status:100
    msg:成功
    url:127.0.0.1/books/1
    }

  • 核心:返回结果中提供链接