gin框架 RESTful API

web 应用程序，一般分为前端和后端两个部分。前后端通信通常需要一种统一机制，以方便不同的前端设备与后端进行通信。这种需求导致了 API 构架的流行，甚至出现 "API First" 的设计思想。

RESTful API 是目前比较成熟的一套 web 应用程序的 API 设计理论，用于 web 前后端的数据交互。

关于 RESTful API 知识可以参考 RESTful API 架构介绍 和 RESTful API 设计指南 的两章的内容。

 

1. RESTful API 路径

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

在 RESTful 架构中，每个网址代表一种资源（resource），比如：有一个 API 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样：

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

 

2. RESTful API HTTP 动词

在 RESTful API 设计理论中，对于资源的操作，由 HTTP 动词表示。

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

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

DELETE（DELETE）：从服务器删除资源。

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

  • HEAD：获取资源的元数据。
  • OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
下面是一些例子。
  • 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：删除某个指定动物园的指定动物

 

3. gin 框架 RESTful API

gin 框架支持 RESTful 风格的 API。

RESTful 即 Representational State Transfer 的缩写。直接翻译的意思是 "表现层状态转化"，是一种互联网应用程序的API设计理念：URL 定位资源，用 HTTP 方法描述操作，例如：

  • 1.获取文章 /blog/getXxx Get blog/Xxx
  • 2.添加文章 /blog/addXxx POST blog/Xxx
  • 3.修改文章 /blog/updateXxx PUT blog/Xxx
  • 4.删除文章 /blog/delXxxx DELETE blog/Xxx

web 程序中经常需要处理各种形式的参数，参数是处理 HTTP 请求中很重要的工作，它是前端提交数据的基本形式。gin 框架内置了处理 HTTP 各种参数的方法，包括 API 参数，URL 参数 以及 表单参数的处理。