T
traeai
登录
返回首页
Towards Data Science

超越模型：为何数据科学家必须拥抱API和API文档

7.8Score
超越模型：为何数据科学家必须拥抱API和API文档

TL;DR · AI 摘要

数据科学家应掌握API及文档技能，以提升协作效率、模型复现性和业务集成能力。

核心要点

  • API是程序间通信的接口，如图书馆管理员简化信息获取过程
  • REST API使用JSON/XML格式，支持GET/POST/PUT等HTTP方法
  • 良好API文档需包含端点、参数和响应说明，提高团队协作效率

结构提纲

按章节快速跳转。

  1. §引言

    API技能对数据科学家团队协作和项目交付至关重要。

  2. ·API定义与作用

    API作为中介连接用户与数据源，简化信息访问流程。

  3. ›REST API核心组件

    资源、HTTP方法、请求响应、头部信息和状态码构成REST API基础。

  4. ·API文档的重要性

    高质量API文档有助于模型复现、新人入职和业务集成。

  5. ›实际应用案例

    通过调用REST API获取实时数据，如The Cat API示例。

思维导图

用一张图看清主题之间的关系。

查看大纲文本（无障碍 / 无 JS 友好）
  • API与数据科学
    • API基础概念
      • 接口定义
      • 中间件角色
    • REST API组成
      • 资源识别
      • HTTP方法
    • 文档价值
      • 协作效率
      • 模型复现

金句 / Highlights

值得收藏与分享的关键句。

#API#数据科学#REST#文档#协作
打开原文

1. 引言

在统计学、编程和人工智能等多个领域的交汇点上，传达复杂方法和见解的能力变得至关重要。因此，掌握全面的 API 概念对于团队内部的有效沟通至关重要。

首先，它促进了团队成员和利益相关者之间的协作。数据科学（DS）项目通常涉及由数据专家、软件开发人员、业务分析师、项目经理等组成的跨学科团队。良好的 API 文档充当了所有这些角色之间的桥梁，使这些不同的群体能够正确理解并使用 DS 模型和工具。

其次，高质量的 API 文档可以提高可重复性，并可能缩短新成员的入职时间。在数据科学中，模型和分析必须经过验证和复制，清晰的 API 文档确保其他人可以遵循相同的流程、使用相同的数据并获得一致的结果。这在制定数据驱动的决策时尤为重要。

最后，随着数据科学越来越多地融入商业战略，良好的 API 文档可以提升数据解决方案的可扩展性，并简化数据处理过程。例如，API 在项目数据收集方面可以发挥重要作用，支持快速原型设计和依赖最新信息的应用程序开发。通过利用像 REST Countries 这样的数据源获取数据（见案例 6.1），数据科学家可以专注于分析而不是数据获取。

在本文中我们将：

  • 简要探讨什么是 API 及其在软件开发中的作用。
  • 了解 REST API 的主要组件。
  • 描述最常见的格式，并提供 API 调用和响应的实际案例。
  • 总结好的 API 文档应具备哪些要素，包括端点、参数和响应信息。

2. 什么是 API

API（应用程序编程接口）是一组方法，用于不同程序之间相互通信和交换数据。本质上，它是一个中介，允许应用程序、设备、服务器和其他系统交换信息，同时隐藏每个系统内部的过程。

想象一个拥有大量图书收藏的图书馆，以及一位知道如何找到特定读者所需书籍的图书管理员。在这里，我们可以将图书管理员视为一个 API，它简化了访问信息的过程，让读者（我们的“前端”）不必花费时间在整本图书目录（我们的“后端”）中搜索，只需专注于他们的具体请求即可。此外，如果读者需要其他书籍，他们可以再次向 API 发送请求来重复该过程。

图像 1

图像由作者使用 NightCafé 创作

这个类比突出了 API 作为用户与数据源之间的中介角色，提供了便捷高效的访问信息方式。

API 的一种特殊情况是 REST API，它遵循 REST（表述性状态转移）架构的概念。REST API 被称为行业标准，因为它们轻量级、灵活，并使用常见的数据格式如 JSON 或 XML。

3. REST API 的组件

下面列出的每个 REST API 组件都在组织客户端-服务器交互中起着至关重要的作用。

3.1. 资源

资源是可以通过 API 访问的任何实体。每个资源都有一个唯一的标识符（URI），例如：

https://api.thecatapi.com/v1/images/search?size=med

在这里，images 是来自 The Cat API 网页 [1] 的猫图片集合，而 search?size=med 是仅查看中等尺寸图片的过滤器。

3.2. HTTP 方法

HTTP 方法用于与资源交互：

  • GET — 获取资源的数据；
  • POST — 创建新资源；
  • PUT — 更新资源；
  • PATCH — 部分更新资源；
  • DELETE — 删除资源。

3.3. 请求和响应

客户端和服务器之间通过 HTTP 请求和响应交换数据。在大多数情况下，使用 JSON 格式，因为它易于阅读并且被绝大多数编程语言支持。

3.4. HTTP 头部

头部用于传递附加信息，例如内容类型（Content-Type）或认证参数（Authorization）。

#### 3.5. HTTP 响应状态码

每个 HTTP 请求都会收到一个带有特定状态码的响应：

  • 200 OK — 请求成功；
  • 201 Created — 资源创建成功；
  • 400 Bad Request — 客户端请求错误；
  • 401 Unauthorized — 缺少访问权限；
  • 404 Not Found — 找不到资源；
  • 500 Internal Server Error — 服务器端错误。

4. API 客户端

Postman 或 Bruno [2] 等 API 客户端通过提供专门的工作区来发送请求和管理响应，简化了 API 交互。与我们在案例 6.1 中使用的命令行工具或编写代码不同，这些工具提供了可视化界面和自动化功能，从而加快了工作流程。

因此，在案例 6.2 中，我们将考虑使用 Bruno 与 JokeAPI 网站 [3] 进行交互。使用 Bruno 简化了不同软件系统之间的复杂交互过程。如果没有 Bruno 和其他 API 客户端，开发者就必须手动构建每一个 HTTP 请求并从头开始处理每一个原始响应。

5. 创建良好 API 文档的技巧

创建有效的 API 文档对于确保用户能够轻松理解和使用您的 API 至关重要。以下是一些需要牢记的关键技巧：

5.1. 优先考虑简洁性、清晰性和一致性

避免使用技术术语和不一致的表达方式。相反，应使用简单明了的语言，便于理解。如有必要，可以建立一个样式指南以在整个文档中保持统一性。在此您可以列出文档中使用的主规则，例如如何格式化代码片段、截图、偏好的语气等。

5.2. 包含全面的细节

完整的 API 文档应包含几个关键要素，特别是典型的 API 方法页面应包括：

  • 简短描述（1-2 句话）：明确概述端点的主要用途。
  • 请求语法：API 调用的概览。
  • 认证方法：详细说明访问 API 所需的安全认证流程。
  • 参数和数据类型：指定请求所需的参数及其对应的数据类型。
  • 请求示例：提供正确请求和带错误的请求示例，以展示如何有效使用 API。

6. 实际案例

案例 6.1：使用 Python 向 RESTful API 发送请求

收集国家层面的数据对于了解全球、区域或国家趋势至关重要，这有助于政府、企业和个体研究人员做出明智决策。在处理像 REST Countries 网站 [4] 这样的国家数据时，数据科学家可以通过 RESTful API 获取有关国家的信息，高效地获取面积、人口和居民称谓等数据，而无需手动抓取大量网页数据。下面的代码获取并显示中美洲国家的数据：

code
import requests
import json

url = 'https://restcountries.com/v3.1/subregion/Central America/?fields=name,area,population,demonyms'
response = requests.get(url)
jdata = response.json()
formatted_json = json.dumps(jdata, indent=4)
print(formatted_json)

地理区域使用联合国方法论定义 [5]。您还可以对特定字段进行过滤 [6]：在本例中，这些字段是名称、面积、人口数量和居民称谓。

输出结果是一个可读性强的 JSON 文件：

json
[
    {
        "name": {
            "common": "洪都拉斯",
            "official": "洪都拉斯共和国",
            "nativeName": {
                "spa": {
                    "official": "República de Honduras",
                    "common": "Honduras"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "洪都拉斯人",
                "m": "洪都拉斯人"
            },
            "fra": {
                "f": "洪都拉斯ienne",
                "m": "洪都拉斯ien"
            }
        },
        "area": 112492.0,
        "population": 9892632
    },
    {
        "name": {
            "common": "哥斯达黎加",
            "official": "哥斯达黎加共和国",
            "nativeName": {
                "spa": {
                    "official": "República de Costa Rica",
                    "common": "Costa Rica"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "哥斯达黎加人",
                "m": "哥斯达黎加人"
            },
            "fra": {
                "f": "哥斯达黎卡ienne",
                "m": "哥斯达黎加in"
            }
        },
        "area": 51100.0,
        "population": 5309625
    },
    {
        "name": {
            "common": "危地马拉",
            "official": "危地马拉共和国",
            "nativeName": {
                "spa": {
                    "official": "República de Guatemala",
                    "common": "Guatemala"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "危地马拉人",
                "m": "危地马拉人"
            },
            "fra": {
                "f": "瓜地马拉que",
                "m": "瓜地马拉que"
            }
        },
        "area": 108889.0,
        "population": 18079810
    },
    {
        "name": {
            "common": "巴拿马",
            "official": "巴拿马共和国",
            "nativeName": {
                "spa": {
                    "official": "República de Panamá",
                    "common": "Panamá"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "巴拿马人",
                "m": "巴拿马人"
            },
            "fra": {
                "f": "巴拿马enne",
                "m": "巴拿马en"
            }
        },
        "area": 75417.0,
        "population": 4064780
    },
    {
        "name": {
            "common": "尼加拉瓜",
            "official": "尼加拉瓜共和国",
            "nativeName": {
                "spa": {
                    "official": "República de Nicaragua",
                    "common": "Nicaragua"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "尼加拉瓜人",
                "m": "尼加拉瓜人"
            },
            "fra": {
                "f": "尼加拉瓜enne",
                "m": "尼加拉瓜en"
            }
        },
        "area": 130373.0,
        "population": 6803886
    },
    {
        "name": {
            "common": "伯利兹",
            "official": "伯利兹",
            "nativeName": {
                "bjz": {
                    "official": "Belize",
                    "common": "Belize"
                },
                "eng": {
                    "official": "Belize",
                    "common": "Belize"
                },
                "spa": {
                    "official": "Belice",
                    "common": "Belice"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "伯利兹人",
                "m": "伯利兹人"
            },
            "fra": {
                "f": "伯利兹ienne",
                "m": "伯利兹ien"
            }
        },
        "area": 22966.0,
        "population": 417634
    },
    {
        "name": {
            "common": "萨尔瓦多",
            "official": "萨尔瓦多共和国",
            "nativeName": {
                "spa": {
                    "official": "República de El Salvador",
                    "common": "El Salvador"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "萨尔瓦多人",
                "m": "萨尔瓦多人"
            },
            "fra": {
                "f": "萨尔瓦多ienne",
                "m": "萨尔瓦多ien"
            }
        },
        "area": 21041.0,
        "population": 6029976
    }
]

案例 6.2：使用 Bruno 向 JokeAPI 发送请求

JokeAPI 是一个免费的开源 REST API，可以以多种格式提供笑话，例如 JSON、XML、YAML 或纯文本 [3]。

  1. 打开 Bruno 并选择 Collections → + Create collection。
  2. 为你的集合指定一个名称，例如 Sample API。
  3. 创建的集合会显示在左侧面板中。要创建请求，请点击 … → New Request。
  4. 选择请求类型（HTTP）并指定其名称，例如 joke_request。
  5. 在 URL 单元格中，选择方法（GET）并输入端点 https://v2.jokeapi.dev/joke/Any?blacklistFlags=religious,political,racist,sexist&type=single。

URL 是根据你在 JokeAPI 网站上选择的偏好构建的。在我们的示例中，我们选择了除 nsfw、宗教、政治、种族主义和性别歧视之外的任何笑话类别（这些类别被标记并列入了黑名单）。

  1. 我们在网站上选择并复制的参数出现在请求中的 ? 后面，作为 GET 字段中端点 URL 的查询字符串，彼此之间用 & 分隔。它们也会出现在 Params 标签页中的表格里。
  2. 点击 Send，稍等片刻……你会收到一个还不错的结果（“生成随机数的重要性不容许交给运气决定。”）。请注意请求的状态——它是 200 OK，表示成功。
Image 2

Bruno 界面的外观。作者拍摄的截图。

需要注意的是，在这个例子中，我们没有要求 API 密钥来访问我们的 REST API 资源。否则，我们需要在单独的 Headers 标签页中将其作为头部传递。

案例 6.3：使用 API 密钥向 NASA 开放 API 发起请求

NASA 的 APOD（每日天文图片）是一个流行的服务，它为用户提供与天文学相关的每日照片或视频以及描述 [7]。

让我们基于第五段提示简要演示一下 NASA APOD API 文档示例。

NASA APOD API 文档

描述：此 API 允许用户检索特定日期、日期范围或随机选择的来自 NASA APOD 网站的图像或视频。

请求语法：GET https://api.nasa.gov/planetary/apod

认证方式：要访问 APOD API，应在请求中包含 API 密钥。要获取免费的 API 密钥，你需要在 https://api.nasa.gov/ 注册。该密钥应作为查询参数包含在请求中。

参数和数据类型：见下表

参数 类型 描述 api_key* string 你的个人 NASA API 密钥。如果未指定，可以使用 DEMO_KEY 来查看请求的样子 date string (datetime) 要检索的 APOD 图像的日期。如果未指定，默认为今天 start_date string (datetime) 检索图像的日期范围开始。不能与 date 参数一起使用 end_date string (datetime) 检索图像的日期范围结束。与 start_date 一起使用在同一请求中 count integer 返回指定数量的随机选择图像。不要与日期时间参数一起使用 thumbs boolean 如果为 true，则返回视频缩略图的 URL。如果 APOD 对象不是视频，则忽略此参数

  • — 必需参数

请求示例

_状态码为 200 OK 的正确请求_

GET`https://api.nasa.gov/planetary/apod?api_key=<your_API_key>`

code
{
    "copyright": "Simone Curzi",
    "date": "2026-05-18",
    "explanation": "螺旋星系 NGC 3169 看起来像是解开了一团宇宙纱线。它位于距离明亮恒星 Regulus 南方约 7000 万光年的地方，朝向微弱的星座 Sextans。当 NGC 3169（左）与邻近的 NGC 3166 相互引力作用时，缠绕的螺旋臂被拉成宽阔的潮汐尾。最终，这两个星系会合并成一个，这是本地宇宙中明亮星系的共同命运。在深邃而多彩的星系群照片中，拉伸的恒星弧和羽状物清楚地表明了正在进行的引力相互作用。望远镜画面跨度约为 20 弧分，即在该星系群估计距离下的约 40 万光年，其中包括右侧较小的蓝色 NGC 3165。NGC 3169 还能在从射电到 X 射线的整个光谱范围内发光，其核心是一个活跃星系核，是超大质量黑洞所在的位置。",
    "hdurl": "https://apod.nasa.gov/apod/image/2605/ngc3169_ngc3166_ngc3165.jpg",
    "media_type": "image",
    "service_version": "v1",
    "title": "解体的 NGC 3169",
    "url": "https://apod.nasa.gov/apod/image/2605/ngc3169_ngc3166_ngc3165px1024.jpg"
}

_用于日期范围的 200 OK 状态的正确请求_

GET https://api.nasa.gov/planetary/apod?start_date=2025-03-03&end_date=2025-03-05&api_key=<your_API_key>

7. 结论

阅读（甚至编写）API 文档不仅仅是技术任务；它是成功数据分析实践的重要组成部分，能够提高协作性、可重复性、采用率和可扩展性。通过优先考虑清晰和详细的文档，数据科学家可以确保自己能够舒适地使用现代工具。

例如，许多数据科学家现在使用像 Claude Code 这样的工具，这是一种编码 AI 代理。使用 Claude Code 时，您的文件存储在本地计算机上，AI 助手从那里读取文件并将文本内容发送到 Anthropic API 进行处理。值得注意的是，Claude API 的全面文档描述了其操作的所有细微差别。具体来说，Claude API 是一个位于 https://api.anthropic.com 的 RESTful API，提供了对 Claude 模型和托管 Claude 代理的程序化访问 [8]。希望在阅读完这篇文章后，您能更好地理解此类（及其他）文档 Image 3: 🙂

感谢阅读！

参考文献列表

  1. 猫咪 API 网页：https://thecatapi.com/
  2. Bruno 文档：https://docs.usebruno.com/introduction/getting-started
  3. 笑话 API 网页：https://jokeapi.dev/
  4. REST 国家 v3.1：https://restcountries.com/
  5. 联合国统计司方法论：用于统计用途的标准国家或地区代码（M49）
  6. 项目 GitLab 页面上的字段列表：https://gitlab.com/restcountries/restcountries/-/blob/master/FIELDS.md
  7. NASA 开放 API：https://api.nasa.gov/
  8. Claude API 文档 — 概述：https://platform.claude.com/docs/en/api/overview

AI 可能会生成不准确的信息，请核实重要内容

超越模型：为何数据科学家必须拥抱API和API文档 | Towards Data Science | traeai