使用Python构建REST API，原理和构建实战

互联网有大量数据，许多网络服务（如 YouTube 和 GitHub）通过API提供数据。构建 API 最流行的方法之一是REST。
Python 有很多开源库，不仅可以获取网络上的数据（爬虫），在这里插入代码片还可以提供API接口给别人调用。

REST Web服务可以是任何遵守REST约束的网络服务。

例如，GitHub 的 REST API：

https://api.github.com/users/`

允许你访问指定 GitHub 用户的信息

HTTP Method

REST API 依赖HTTP Method

HTTP Method告诉 API 对资源执行哪个操作。

虽然有许多 HTTP Method，但下面列出的五种是 REST API 最常用的：

HTTP方法	描述
GET	检索现有资源。
POST	创建新资源。
PUT	更新现有资源。
PATCH	部分更新现有资源。
DELETE	删除资源。

REST API 客户端可以使用这五种 HTTP Method来管理 Web 服务中的资源状态。

状态码

以下是 REST API 返回的最常见状态码的列表：

代码	意义	描述
200	成功	请求的操作成功。
201	已创建	已创建新资源。
202	收到	已收到请求，但尚未进行任何修改。
204	无内容	请求成功，但响应没有内容。
400	错误的请求	请求格式错误。
401	未经授权	客户端无权执行请求的操作。
404	未找到	未找到请求的资源。
415	不支持的媒体类型	服务器不支持请求数据格式。
422	不可处理	请求数据的格式正确，但包含无效或丢失的数据。
500	内部服务器错误	服务器在处理请求时抛出错误。

这十个状态码仅是HTTP 状态码的一小部分。状态码根据结果的类别进行编号：

代码范围	类别
2xx	操作成功
3xx	重定向
4xx	客户端错误
5xx	服务器错误

HTTP 状态码在使用 REST API 时会派上用场，你经常需要根据响应状态码执行不同的逻辑。

使用 API

业界流行请求库requests，这个库封装了 HTTP 请求的复杂操作，提供简单的调用api。

使用pip安装：

• $ python -m pip install requests

GET

GET是使用 REST API 时最常用的 HTTP Method之一。

GET允许你从给定的 API 检索资源。

GET是只读操作，不应使用它来修改现有资源。

举例(建议启动python跟着敲一下):

>>> import requests
>>> api_url = "https://jsonplaceholder.typicode.com/todos/1"
>>> response = requests.get(api_url)
>>> response.json()
{'userId': 1, 'id': 1, 'title': 'delectus aut autem', 'completed': False}

代码调用requests.get()向 发送GET请求/todos/1

请求以todo具有 ID的项目进行响应1。然后你可以调用.json()(https://docs.python-requests.org/en/master/user/quickstart/#json-response-content)该response对象以查看从 API 返回的数据。

响应数据的格式为JSON，类似于[Python 字典]的键值存储，JSON是非常流行的数据格式，也是大多数 REST API 的事实上的交换格式。

查看其他response内容：

>>>
>>> response.status_code
200
>>> response.headers["Content-Type"]
'application/json; charset=utf-8'

其他HTTP头

PUT

发送PUT请求更新现有数据。

>>>
>>> import requests
>>> api_url = "https://jsonplaceholder.typicode.com/todos/10"
>>> response = requests.get(api_url)
>>> response.json()
{'userId': 1, 'id': 10, 'title': 'illo est ... aut', 'completed': True}

>>> todo = {"userId": 1, "title": "Wash car", "completed": True} 
>>> response = requests.put(api_url, json=todo) 
>>> response.json() {'userId': 1, 'title': 'Wash car', 'completed': True, 'id': 10}
>>> response.status_code
200

PATCH

PATCH对比PUT

• PATCH更新对象部分属性
• PUT更新整个对象

举例：更新title：

>>>
>>> import requests
>>> api_url = "https://jsonplaceholder.typicode.com/todos/10"
>>> todo = {"title": "Mow lawn"} 
>>> response = requests.patch(api_url, json=todo) 
>>> response.json()
{'userId': 1, 'id': 10, 'title': 'Mow lawn', 'completed': True}

>>> response.status_code
200

title已更新为Mow lawn.

DELETE

完全删除资源

这是删除 a 的代码todo：

>>>
>>> import requests
>>> api_url = "https://jsonplaceholder.typicode.com/todos/10"
>>> response = requests.delete(api_url) 
>>> response.json()
{}

>>> response.status_code
200

删除资源后，API 返回一个空的 JSON 对象，表示该资源已被删除。

构建 API

REST API 设计是一个很大主题，下面是一些建议步骤。

定义你的端点(URI/或者说是服务提供者)

1. 确认资源
2. 根据资源来定义 API 端点。

以下是transactions支付处理服务示例端点：

HTTP方法	API 端点	描述
GET	/transactions	获取交易列表。
GET	/transactions/<transaction_id>	获得单笔交易。
POST	/transactions	创建一个新的事务。
PUT	/transactions/<transaction_id>	更新交易。
PATCH	/transactions/<transaction_id>	部分更新事务。
DELETE	/transactions/<transaction_id>	删除交易。

涵盖了创建、读取、更新和删除的所有操作。

注意：端点不应包含动词。

例如，下面的端点包含一个不需要的动词：

• GET /getTransactions

get不需要包含在端点中，HTTP MethodGET已经为端点提供了语义，应该删除get：

• GET /transactions

此端点仅包含复数名词，HTTP MethodGET 提示端点是用来干嘛的。

看一个嵌套资源的端点示例，guests嵌套在events资源下的端点：

HTTP方法	API 端点	描述
GET	/events/<event_id>/guests	获取客人名单。
GET	/events/<event_id>/guests/<guest_id>	得到一个客人。
POST	/events/<event_id>/guests	创建一个新的客人。
PUT	/events/<event_id>/guests/<guest_id>	更新客人。
PATCH	/events/<event_id>/guests/<guest_id>	部分更新访客。
DELETE	/events/<event_id>/guests/<guest_id>	删除访客。

使用这些端点，你可以管理系统guests中的特定事件。

这不是定义嵌套资源端点的唯一方法，有些人更喜欢使用查询字符串来访问嵌套资源，查询字符串允许HTTP 请求发送附加参数。

举例：查询字符串获取guests特定的event_id：

• GET /guests?event_id=23

你需要决定哪种方法最适合你。

注意：你的 REST API 不太可能在你的 Web 服务的整个生命周期中保持不变。资源会发生变化，你需要更新端点以反映这些变化。这就是API 版本控制的用武之地。 API 版本控制允许你修改 API，而不必担心破坏现有集成。

有很多版本控制策略，选择取决于你的 API 的要求，下面是一些流行的 API 版本控制方式：

• URI 版本控制
• HTTP 头版本控制
• 查询字符串版本控制
• 媒体类型版本控制

无论你选择何种策略，对 API 进行版本控制都是确保它能够适应不断变化的需求同时支持现有用户的重要方式。

结论

REST API 无处不在。
使用 Python不仅可以请求REST API，还可以构建 REST API。
为各种有趣的、数据驱动的服务打开了大门。