REST 和 API 介绍
- REST
在 2000 年,Roy Fielding 提议使用表述性状态转移 (REST) 作为设计 Web 服务的体系性方法。 REST 是一种基于超媒体构建分布式系统的架构风格。 REST 独立于任何基础协议,并且不一定绑定到 HTTP。 但是,最常见的 REST 实现使用 HTTP 作为应用程序协议,本指南重点介绍如何设计适用于 HTTP 的 REST API。
基于 HTTP 的 REST 的主要优势在于它使用开放标准,不会绑定 API 的实现,也不会将客户端应用程序绑定到任何具体实现。 例如,可以使用 ASP.NET 编写 REST Web 服务,而客户端应用程序能够使用任何语言或工具来发起 HTTP 请求和分析 HTTP 响应。 - API
API(Application Programming Interface,应用程序接口)是一些预先定义的函数,或指软件系统不同组成部分衔接的约定。 目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问原码,或理解内部工作机制的细节。
Github API 介绍
官方文档
可参考B1u3Buf4的博客简单使用。
可以直接再浏览器上输入:
https://api.github.com/users/chenjb
users/后面+自己的github用户名,获取用户信息
{
"login": "chenjb",
"id": 4031969,
"node_id": "MDQ6VXNlcjQwMzE5Njk=",
"avatar_url": "https://avatars1.githubusercontent.com/u/4031969?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/chenjb",
"html_url": "https://github.com/chenjb",
"followers_url": "https://api.github.com/users/chenjb/followers",
"following_url": "https://api.github.com/users/chenjb/following{/other_user}",
"gists_url": "https://api.github.com/users/chenjb/gists{/gist_id}",
"starred_url": "https://api.github.com/users/chenjb/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/chenjb/subscriptions",
"organizations_url": "https://api.github.com/users/chenjb/orgs",
"repos_url": "https://api.github.com/users/chenjb/repos",
"events_url": "https://api.github.com/users/chenjb/events{/privacy}",
"received_events_url": "https://api.github.com/users/chenjb/received_events",
"type": "User",
"site_admin": false,
"name": null,
"company": null,
"blog": "",
"location": null,
"email": null,
"hireable": null,
"bio": null,
"public_repos": 6,
"public_gists": 0,
"followers": 2,
"following": 5,
"created_at": "2013-04-02T01:41:12Z",
"updated_at": "2019-05-20T05:53:00Z"
}
REST API 的设计原则
- REST API 围绕资源设计,资源是可由客户端访问的任何类型的对象、数据或服务。
- 每个资源有一个标识符,即,唯一标识该资源的 URI。 例如,特定客户订单的 URI 可能是:
https://adventure-works.com/orders/1
- 客户端通过交换资源的表示形式来与服务交互。 许多 Web API 使用 JSON 作为交换格式。 例如,对上面所列的 URI 发出 GET 请求可能返回以下响应正文:
{"orderId":1,"orderValue":99.90,"productId":1,"quantity":1}
- REST API 使用统一接口,这有助于分离客户端和服务实现。 对于基于 HTTP 构建的 REST API,统一接口包括使用标准 HTTP 谓词对资源执行操作。 最常见的操作是 GET、POST、PUT、PATCH 和 DELETE。
- REST API 使用无状态请求模型。 HTTP 请求应是独立的并可按任意顺序发生,因此保留请求之间的瞬时状态信息并不可行。 信息的唯一存储位置就在资源内,并且每个请求应是原子操作。 此约束可让 Web 服务获得高度可伸缩性,因为无需保留客户端与特定服务器之间的关联。 任何服务器可以处理来自任何客户端的任何请求。 也就是说,其他因素可能会限制可伸缩性。 例如,许多 web 服务都写入后端数据存储,这可能很难横向扩展。有关横向扩展数据存储的策略的详细信息,请参阅水平、垂直和功能数据分区。
- REST API 由表示形式中包含的超媒体链接驱动。 例如,下面显示了某个订单的 JSON 表示形式。 该表示形式包含一些链接,用于获取或更新与该订单关联的客户。
{
"orderID":3,
"productID":2,
"quantity":4,
"orderValue":16.60,
"links": [
{"rel":"product","href":"https://adventure-works.com/customers/3", "action":"GET" },
{"rel":"product","href":"https://adventure-works.com/customers/3", "action":"PUT" }
]
}
2008 年,Leonard Richardson 提议对 Web API 使用以下成熟度模型:
级别 0:定义一个 URI,所有操作是对此 URI 发出的 POST 请求。
级别 1:为各个资源单独创建 URI。
级别 2:使用 HTTP 方法来定义对资源执行的操作。
级别 3:使用超媒体(HATEOAS,如下所述)。
根据 Fielding 的定义,级别 3 对应于某个真正的 RESTful API。 在实践中,许多发布的 Web API 大致处于级别 2。
- 根据HTTP方法定义操作
Verb | 描述 |
---|---|
HEAD | 只获取某个资源的头部信息 |
GET(SELECT) | 从服务器取出资源 |
POST(CREATE) | 在服务器新建一个资源 |
PUT(UPDATE) | 在服务器更新资源(客户端提供改变后的完整资源) |
PATCH(UPDATE) | 在服务器更新资源(客户端提供改变的属性) |
DELETE(DELETE) | 从服务器删除资源 |
Github API 设计
根据上节课所学内容可以进行相关的设计
- 登录
curl -u username -p password https://api.exampleBlog.com
成功登陆的返回状态码是2xx;失败的返回码是4xx,有以下几种情况:
报错 | 错误原因 |
---|---|
400 Bad request | 指令错误 |
401 Unauthorized | 密码错误 |
403 Forbidden | 访问过于频繁 |
404 Not found | 账户不存在 |
- 查看文章
curl -a https://api.exampleBlog.com/chenjb58/articles
- 评论
curl -c 'my comments' https://api.exampleBlog.com/chenjb58/article/1/comments
- 删除文章
curl -d -i https://api.exampleBlog.com/chenjb58/delete/article?id=1