Api设计go学习

RESTfull API

2016-03-29  本文已影响783人  daoyidao

介绍

现在的网络应用程序，分为前端和后端两个部分， 采用客户端/服务器 模式。

后端建立在分布式体系上，通过互联网通信，具有高延时（high latency）、高并发等特点；前端设备层出不穷（如手机、平板、桌面电脑、其他专用设备......）。

each client app has its own embedded business logic

因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现"API First"的设计思想。

central API which hold all the business logic

目前，有三种主流的Web服务交互方案：

RESTful架构，是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。

概念简述

REST（Representational State Transfer）这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的。

Fielding是HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。

他写的关于RESTful的论文是这样描述的：

"本文研究计算机科学两大前沿----软件和网络----的交叉点。长期以来，软件研究主要关注软件设计的分类、设计方法的演化，很少客观地评估不同的设计选择对系统行为的影响。而相反地，网络研究主要关注系统之间通信行为的细节、如何改进特定通信机制的表现，常常忽视了一个事实，那就是改变应用程序的互动风格比改变互动协议，对整体表现有更大的影响。我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。"

Fielding将他对互联网软件的架构原则，定名为REST，即Representational State Transfer的缩写，翻译为"表现层状态转化"。

如果一个架构符合REST原则，就称它为RESTful架构。

主要的原则：

简单总结

什么是RESTful架构：

  1. 每一个URI代表一种资源；
  2. 客户端和服务器之间，传递这种资源的某种表现层；
  3. 客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

误区

正确的写法是把动词transfer改成名词transaction，资源不能是动词，但 是可以是一种服务：
POST /transaction HTTP/1.1
Host: 127.0.0.1
from=1&to=2&amount=500.00

RESTful API

  1. 协议

    API与用户的通信协议，总是使用HTTPs协议(SSL/TLS)。

  2. 域名

    应该尽量将API部署在专用域名之下。
    https://api.example.com

    如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

     https://example.org/api/

  3. 版本（Versioning）：

    • 将API的版本号放入URL。

       https://api.example.com/v1/
  1. 路径（Endpoint）

路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

    https://api.example.com/v1/zoos
    https://api.example.com/v1/animals
    https://api.example.com/v1/employees
  1. HTTP动词

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

还有两个不常用的HTTP动词。

下面是一些例子。

    GET /zoos：列出所有动物园
    POST /zoos：新建一个动物园
    GET /zoos/ID：获取某个指定动物园的信息
    PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
    PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
    DELETE /zoos/ID：删除某个动物园
    GET /zoos/ID/animals：列出某个指定动物园的所有动物
    DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
  1. 过滤信息（Filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

    ?limit=10：指定返回记录的数量
    ?offset=10：指定返回记录的开始位置。
    ?page=2&per_page=100：指定第几页，以及每页的记录数。
    ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
    ?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

  1. 状态码（Status Codes）

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

  1. 错误处理（Error handling）

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。
{
error: "Invalid API key"
}

  1. 返回结果

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

  1. Hypermedia API

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

比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

      {"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"
}

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

  1. 其他

参考资料：

上一篇下一篇

猜你喜欢

热点阅读