API и документация: почему разработчикам необходимо использовать API в своей работе

Раскройте потенциал API для решений, основанных на данных.

Делиться

1. Введение

Поскольку специалисты по анализу данных работают на стыке различных областей — статистики, программирования, искусственного интеллекта — умение доносить сложные методологии и выводы становится крайне важным. Таким образом, умение работать с комплексными концепциями API необходимо для эффективной коммуникации внутри команды.

Во-первых, это способствует сотрудничеству между членами команды и заинтересованными сторонами. Проекты в области науки о данных (DS) часто включают междисциплинарные команды, состоящие не только из специалистов по данным, но и из разработчиков программного обеспечения, бизнес-аналитиков, менеджеров проектов и т. д. Хорошо документированные API служат мостом между всеми ними, позволяя этим разнородным группам понимать и правильно использовать модели и инструменты DS.

Во-вторых, высококачественная документация API повышает воспроизводимость и может сократить время адаптации для новых пользователей. В сфере разработки программного обеспечения, где модели и анализы должны быть проверены и воспроизведены, четкая документация API гарантирует, что другие смогут следовать тем же процессам, использовать те же данные и получать согласованные результаты. Это особенно важно при разработке решений, основанных на данных.

Наконец, по мере того как наука о данных все больше интегрируется в бизнес-стратегии, хорошо документированные API могут повысить масштабируемость решений для работы с данными и упростить процесс работы с данными. Например, API могут играть важную роль в сборе данных для проектов, обеспечивая быстрое прототипирование и разработку приложений, которые полагаются на актуальную информацию. Используя API для сбора данных из таких источников, как REST Countries (см. пример 6.1), специалисты по данным могут сосредоточиться на анализе, а не на сборе данных.

В этой статье мы рассмотрим:

• Кратко опишите, что такое API и для чего он нужен в разработке программного обеспечения.
• Ознакомьтесь с основными компонентами REST API.
• Опишите наиболее распространенные форматы и приведите практические примеры вызовов и ответов API.
• Вкратце опишите, как должна выглядеть хорошая документация API, содержащая информацию о конечных точках, параметрах и ответах.

2. Что такое API?

API (интерфейс прикладного программирования) представляет собой набор методов, с помощью которых различные программы взаимодействуют друг с другом и обмениваются данными. По сути, это посредник, позволяющий приложениям, устройствам, серверам и другим системам обмениваться информацией, скрывая при этом процессы внутри каждой системы друг от друга.

Представьте себе библиотеку с большим собранием книг и библиотекаря, который знает, где найти именно ту книгу, которая нужна конкретному читателю. В этом случае мы можем рассматривать библиотекаря как API, упрощающий процесс доступа к информации, избавляя читателей (наш «фронтенд») от необходимости тратить время на поиск по всему книжному каталогу (наш «бэкенд»), позволяя им сосредоточиться только на своем конкретном запросе. Более того, если читателям нужна другая книга, они могут повторить процесс отправки запроса к API.

Эта аналогия подчеркивает роль API как посредника между пользователем и источником данных, обеспечивающего удобный и эффективный доступ к информации.

Частным случаем API является REST API, который следует концепциям архитектуры REST (REpresentational State Transfer). REST API считаются отраслевым стандартом, поскольку они легковесны, гибки и используют распространенные форматы данных, такие как JSON или XML.

3. Компоненты REST API

Каждый из перечисленных ниже компонентов REST API играет важную роль в организации взаимодействия между клиентом и сервером.

3.1. Ресурсы

Ресурс — это любая сущность, доступная через API. Каждый ресурс имеет уникальный идентификатор (URI), например:

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

Здесь images — это коллекция изображений кошек со страницы веб-API The Cat [1], а search?size=med — это фильтр для просмотра только изображений среднего размера.

3.2. Методы HTTP

Для взаимодействия с ресурсами используются следующие методы HTTP:

• GET — получить данные о ресурсе;
• POST — создать новый ресурс;
• PUT — обновление ресурса;
• PATCH — частичное обновление ресурса;
• УДАЛИТЬ — удалить ресурс.

3.3. Запросы и ответы

Обмен данными между клиентом и сервером осуществляется посредством HTTP-запросов и ответов. В большинстве случаев используется формат JSON, поскольку он легко читается и поддерживается подавляющим большинством языков программирования.

3.4. HTTP-заголовки

Заголовки используются для передачи дополнительной информации, такой как тип контента ( Content-Type ) или параметры аутентификации ( Authorization ).

3.5. Коды ответа HTTP

Каждый HTTP-запрос получает ответ с определенным кодом состояния:

• 200 OK — запрос выполнен успешно;
• 201 Создано — ресурс успешно создан;
• 400 Bad Request — ошибка запроса клиента;
• 401 Несанкционированный доступ — отсутствие прав доступа;
• 404 Not Found — ресурс не найден;
• 500 Internal Server Error — ошибка на стороне сервера.

4. API-клиенты

Клиенты API, такие как Postman или Bruno [2], упрощают взаимодействие с 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: Отправка запроса к RESTful API с использованием Python

Сбор данных на уровне стран имеет важное значение для понимания глобальных, региональных или национальных тенденций, что позволяет правительствам, предприятиям и отдельным исследователям принимать обоснованные решения. При работе с данными по странам, такими как веб-сайт REST Countries [4], специалисты по данным могут получать информацию о странах через RESTful API для эффективного получения данных о площади, населении и названиях без ручного сбора огромного количества веб-данных. Приведенный ниже код извлекает и отображает данные о странах Центральной Америки:

 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-файла:

 [ { "name": { "common": "Honduras", "official": "Republic of Honduras", "nativeName": { "spa": { "official": "Repu00fablica de Honduras", "common": "Honduras" } } }, "demonyms": { "eng": { "f": "Honduran", "m": "Honduran" }, "fra": { "f": "Hondurienne", "m": "Hondurien" } }, "area": 112492.0, "population": 9892632 }, { "name": { "common": "Costa Rica", "official": "Republic of Costa Rica", "nativeName": { "spa": { "official": "Repu00fablica de Costa Rica", "common": "Costa Rica" } } }, "demonyms": { "eng": { "f": "Costa Rican", "m": "Costa Rican" }, "fra": { "f": "Costaricaine", "m": "Costaricain" } }, "area": 51100.0, "population": 5309625 }, { "name": { "common": "Guatemala", "official": "Republic of Guatemala", "nativeName": { "spa": { "official": "Repu00fablica de Guatemala", "common": "Guatemala" } } }, "demonyms": { "eng": { "f": "Guatemalan", "m": "Guatemalan" }, "fra": { "f": "Guatu00e9maltu00e8que", "m": "Guatu00e9maltu00e8que" } }, "area": 108889.0, "population": 18079810 }, { "name": { "common": "Panama", "official": "Republic of Panama", "nativeName": { "spa": { "official": "Repu00fablica de Panamu00e1", "common": "Panamu00e1" } } }, "demonyms": { "eng": { "f": "Panamanian", "m": "Panamanian" }, "fra": { "f": "Panamu00e9enne", "m": "Panamu00e9en" } }, "area": 75417.0, "population": 4064780 }, { "name": { "common": "Nicaragua", "official": "Republic of Nicaragua", "nativeName": { "spa": { "official": "Repu00fablica de Nicaragua", "common": "Nicaragua" } } }, "demonyms": { "eng": { "f": "Nicaraguan", "m": "Nicaraguan" }, "fra": { "f": "Nicaraguayenne", "m": "Nicaraguayen" } }, "area": 130373.0, "population": 6803886 }, { "name": { "common": "Belize", "official": "Belize", "nativeName": { "bjz": { "official": "Belize", "common": "Belize" }, "eng": { "official": "Belize", "common": "Belize" }, "spa": { "official": "Belice", "common": "Belice" } } }, "demonyms": { "eng": { "f": "Belizean", "m": "Belizean" }, "fra": { "f": "Bu00e9lizienne", "m": "Bu00e9lizien" } }, "area": 22966.0, "population": 417634 }, { "name": { "common": "El Salvador", "official": "Republic of El Salvador", "nativeName": { "spa": { "official": "Repu00fablica de El Salvador", "common": "El Salvador" } } }, "demonyms": { "eng": { "f": "Salvadoran", "m": "Salvadoran" }, "fra": { "f": "Salvadorienne", "m": "Salvadorien" } }, "area": 21041.0, "population": 6029976 } ]

Пример 6.2: Отправка запроса к JokeAPI с помощью Bruno

JokeAPI — это бесплатный REST API с открытым исходным кодом, который предоставляет шутки в различных форматах, например, JSON, XML, YAML или в виде простого текста [3].

1. Откройте Bruno и выберите «Коллекции» → «+ Создать коллекцию» .
2. Выберите название для вашей коллекции, например, Sample API .
3. Созданная коллекция отображается в левой панели. Чтобы создать запрос, нажмите … → Новый запрос .
4. Выберите тип запроса ( HTTP ) и укажите его имя, например, joke_request .
5. В ячейке URL выберите метод ( GET ) и введите конечную точку https://v2.jokeapi.dev/joke/Any?blacklistFlags=religious,political,racist,sexist&type=single.
   URL-адрес был сформирован на основе настроек, выбранных вами на веб-сайте JokeAPI. В нашем примере мы выбрали любую категорию шуток, кроме тех, что содержат контент для взрослых, религиозные, политические, расистские и сексистские (они были помечены как неприемлемые и внесены в черный список).
6. Выбранные и скопированные нами на веб-сайте параметры появились в запросе после знака вопроса ? в виде строки запроса к URL-адресу конечной точки в поле GET , разделенные символом & . Они также отобразятся в таблице на вкладке «Параметры» .
7. Нажмите «Отправить» , немного подождите… и в ответ вы получите неплохую шутку («Генерация случайных чисел слишком важна, чтобы полагаться на случай»). Обратите внимание на статус нашего запроса — это 200 OK, что означает успех.

Важно отметить, что в этом примере для доступа к нашему REST API-ресурсу не требовался API-ключ. В противном случае нам пришлось бы передавать его в качестве заголовка на отдельной вкладке «Заголовки» .

Пример 6.3: Отправка запроса в открытые API NASA с использованием ключа API.

APOD (Astronomy Picture of the Day) НАСА — это популярный сервис, предоставляющий пользователям доступ к ежедневным фотографиям или видео, связанным с астрономией, вместе с описанием [7].

Давайте кратко рассмотрим пример документации API NASA APOD, основываясь на советах из 5-го абзаца.

Документация по API NASA APOD

Описание : Этот API позволяет пользователям получать изображения или видео за определенные даты, диапазоны или просто за случайно выбранные периоды с веб-сайта APOD NASA.

Синтаксис запроса : GET https://api.nasa.gov/planetary/apod

Методы аутентификации : Для доступа к API APOD необходимо включить в запрос ключ API. Чтобы получить бесплатный ключ API, нужно зарегистрироваться на сайте https://api.nasa.gov/. Этот ключ следует указать в качестве параметра запроса.

Параметры и типы данных : см. таблицу ниже.

* — необходимые параметры

Примеры запросов

Запрос корректен, статус 200 OK.

GET https://api.nasa.gov/planetary/apod?api_key=

 { "copyright": "Simone Curzi", "date": "2026-05-18", "explanation": "Spiral galaxy NGC 3169 looks to be unraveling like a ball of cosmic yarn. It lies some 70 million light-years away, south of bright star Regulus toward the faint constellation Sextans. Wound up spiral arms are pulled out into sweeping tidal tails as NGC 3169 (left) and neighboring NGC 3166 interact gravitationally. Eventually the galaxies will merge into one, a common fate even for bright galaxies in the local universe. Drawn out stellar arcs and plumes are clear indications of the ongoing gravitational interactions across the deep and colorful galaxy group photo. The telescopic frame spans about 20 arc minutes or about 400,000 light-years at the group's estimated distance, and includes smaller, bluish NGC 3165 to the right. NGC 3169 is also known to shine across the spectrum from radio to X-rays, harboring an active galactic nucleus that is the site of a supermassive black hole.", "hdurl": "https://apod.nasa.gov/apod/image/2605/ngc3169_ngc3166_ngc3165.jpg", "media_type": "image", "service_version": "v1", "title": "Unraveling 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=

 [ { "date": "2025-03-03", "explanation": "There's a new lander on the Moon. Yesterday Firefly Aerospace's Blue Ghost executed the first-ever successful commercial lunar landing. During its planned 60-day mission, Blue Ghost will deploy several NASA-commissioned scientific instruments, including PlanetVac which captures lunar dust after creating a small whirlwind of gas. Blue Ghost will also host the telescope LEXI that captures X-ray images of the Earth's magnetosphere. LEXI data should enable a better understanding of how Earth's magnetic field protects the Earth from the Sun's wind and flares. Pictured, the shadow of the Blue Ghost lander is visible on the cratered lunar surface, while the glowing orb of the planet Earth hovers just over the horizon. Goals for future robotic Blue Ghost landers include supporting lunar astronauts in NASA's Artemis program, with Artemis III currently scheduled to land humans back on the Moon in 2027.", "hdurl": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_4096.jpg", "media_type": "image", "service_version": "v1", "title": "Blue Ghost on the Moon", "url": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_960.jpg" }, { "copyright": "Valerio Minato", "date": "2025-03-04", "explanation": "Why does this Moon look so unusual? A key reason is its vivid red color. The color is caused by the deflection of blue light by Earth's atmosphere -- the same reason that the daytime sky appears blue. The Moon also appears unusually distorted. Its strange structuring is an optical effect arising from layers in the Earth's atmosphere that refract light differently due to sudden differences in temperature or pressure. A third reason the Moon looks so unusual is that there is, by chance, an airplane flying in front. The featured picturesque gibbous Moon was captured about two weeks ago above Turin, Italy. Our familiar hovering sky orb was part of an unusual quadruple alignment that included two historic ground structures: the Sacra di San Michele on the near hill and Basilica of Superga just beyond. Your Sky Surprise: What picture did APOD feature on your friend's birthday? (post 1995)", "hdurl": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg", "media_type": "image", "service_version": "v1", "title": "A Quadruple Alignment over Italy", "url": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg" }, { "copyright": "Todd Anderson", "date": "2025-03-05", "explanation": "On the right, dressed in blue, is the Pleiades. Also known as the Seven Sisters and M45, the Pleiades is one of the brightest and most easily visible open clusters on the sky. The Pleiades contains over 3,000 stars, is about 400 light years away, and only 13 light years across. Surrounding the stars is a spectacular blue reflection nebula made of fine dust. A common legend is that one of the brighter stars faded since the cluster was named. On the left, shining in red, is the California Nebula. Named for its shape, the California Nebula is much dimmer and hence harder to see than the Pleiades. Also known as NGC 1499, this mass of red glowing hydrogen gas is about 1,500 light years away. Although about 25 full moons could fit between them, the featured wide angle, deep field image composite has captured them both. A careful inspection of the deep image will also reveal the star forming region IC 348 and the molecular cloud LBN 777 (the Baby Eagle Nebula). Jump Around the Universe: Random APOD Generator", "hdurl": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_9953.jpg", "media_type": "image", "service_version": "v1", "title": "Seven Sisters versus California", "url": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_960.jpg" } ]

Запрос с ошибкой и статусом 400 Bad Request.

GET https://api.nasa.gov/planetary/apod?date=2023-03-01&end_date=2023-03-01&api_key=

 { "code": 400, "msg": "Bad Request: invalid field combination passed. Allowed request fields for apod method are 'concept_tags', 'date', 'hd', 'count', 'start_date', 'end_date', 'thumbs'", "service_version": "v1" }

7. Заключение

Умение читать (а возможно, и писать) документацию по API — это не просто техническая задача; это жизненно важный компонент успешной практики анализа данных, улучшающий сотрудничество, воспроизводимость, внедрение и масштабируемость. Уделяя приоритетное внимание четкой и подробной документации, специалисты по анализу данных могут быть уверены в своей уверенности в работе с современными инструментами.

Например, многие специалисты по обработке данных сейчас используют такие инструменты, как Claude Code, агент ИИ для кодирования. С Claude Code ваши файлы хранятся локально на вашем компьютере, а ИИ-помощник считывает их оттуда и отправляет текстовое содержимое в Anthropic API для обработки. Стоит отметить, что подробная документация по Claude API описывает все нюансы его работы. В частности, Claude API — это RESTful API по адресу https://api.anthropic.com , который предоставляет программный доступ к моделям Claude и управляемым агентам Claude [8]. Надеюсь, после прочтения этой статьи вы лучше поймете эту (и другую) документацию 🙂

Спасибо за прочтение!

Список использованной литературы

1. Веб-страница Cat API: https://thecatapi.com/
2. Документация Bruno: https://docs.usebruno.com/introduction/getting-starting
3. Веб-страница JokeAPI: https://jokeapi.dev/
4. REST countries v3.1: https://restcountries.com/
5. Методология UNSD: Стандартные коды стран или регионов для статистического использования (M49)
6. Список полей на странице проекта в GitLab: https://gitlab.com/restcountries/restcountries/-/blob/master/FIELDS.md
7. Открытые API NASA: https://api.nasa.gov/
8. Обзор документации API Claude: https://platform.claude.com/docs/en/api/overview

Радмила Манджиева Посмотреть все от Радмилы Манджиевой

Источник: towardsdatascience.com