请求包和 API 文档答案

【问题标题】：Requests package and API documentation请求包和 API 文档
【发布时间】：2018-09-27 14:44:55
【问题描述】：

我无法理解在何处添加 API 文档定义的参数。以 BeeBole 的documentation 为例，它指定要通过 ID 获取缺勤，需要以下请求：

    {
"service": "absence.get",
"id": "absence_id"
}

他们在文档中只提供一个 URL：

BeeBole 接受以下 URL 的 json-doc 格式的 HTTP POST 请求： https://beebole-apps.com/api/v2

这将如何在 Python 请求的上下文中实现？我尝试过的以下代码返回 404：

import requests

payload = {
    "service": "absence.get",
    "id": "absence_id"
}

auth = {
    "username": "API_token",
    "password": "x"
}

url = "https://beebole-apps.com/api/v2"

req = requests.get(url, params=payload, auth=auth).json()

【问题讨论】：

如果是 404，你可能需要仔细检查你使用的 url
它是他们文档中列出的唯一 URL，你确定它与我的参数无关吗？
他们期望的是 JSON 文档，但您发送的是 URL 查询。
嗯，您确定需要auth 密钥参数吗？ headers 中没有？
我可能会使用他们将其包含在 URL 中的示例，因此感谢您选择此内容。

标签： python api python-requests documentation

【解决方案1】：

BeeBole 接受以 json-doc 格式发送到以下 URL 的 HTTP POST 请求：https://beebole-apps.com/api/v2

这里的 JSON 文档格式是你遗漏的部分；您需要将信息作为请求的 JSON 编码 body 传递。您使用的 params 参数仅设置 URL 查询字符串（URL 中的 ?... 部分）。

使用

import requests

payload = {
    "service": "absence.get",
    "id": "absence_id"
}

auth = ("API_token", "x")    
url = "https://beebole-apps.com/api/v2"

req = requests.get(url, json=payload, auth=auth).json()

json= 部分确保payload 字典被编码为 JSON 并作为 POST 正文发送。这也设置了请求的Content-Type 标头。

我还更新了API authentication，这里auth 关键字需要的只是用户名和密码的元组。请参阅Basic Authentication section。

您可能需要等待响应时调用.json()；先检查是否响应成功：

req = requests.get(url, json=payload, auth=auth)
if not req.ok:
    print('Request not OK, status:', req.status_code, req.reason)
    if req.content:
        print(req.text)
else:
    data = req.json()
    if data['status'] == 'error':
        print('Request error:', data['message'])

这使用documented error responses。

【讨论】：

.json() 对吗？我以前没见过这样的要求
@SuperStew：响应有一个 .json() 方法，所以是的，只要响应是 200 成功响应，那么它将起作用。

【解决方案2】：

从站点文档看来，这个特定的供应商选择了一个不寻常的 API。大多数人使用不同的端点来实现不同的操作，但 BeeBole 似乎在一个端点上实现所有东西，然后通过检查请求数据中的"service" 键来选择操作。

试试

response - request.post('https://beebole-apps.com/api/v2',
                        json={"service": "company.list"},
                        headers={"authorization": TOKEN)

从文档中我不能保证会以正确的格式提出请求，但至少如果它不起作用，它应该会给你一些关于如何继续的线索。 BeeBole 文档中的“授权”部分描述了建立TOKEN 的正确值。

这是提供 API 的一种不同寻常的方式，但似乎可行。

【讨论】：