Что такое API и как с ним работать?

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

Самый простой пример: сайт использует API для получения данных о погоде из Яндекс.Погоды или другой сайт использует API для обработки платежей через онлайн-банкинг.

В этой статье разберёмся, что такое API и как он работает на практике, как запустить первые интеграции и научиться разбираться в документации.

Основы работы с API

Если объяснять простыми словами, то работа с API похожа на процесс заказа в ресторане: вы делаете заказ (запрос), а затем получаете ваш заказ от официанта (ответ). В контексте API заказ — это HTTP-запрос, который содержит свои инструкции и данные в нужном формате:

Основные HTTP-запросы:

• GET для запроса данных;
• POST для отправки новых данных на сервер;
• PUT для обновления уже занесённых данных;
• DELETE для удаления данных.

Форматы данных, используемые в API:

• JSON — упрощённый и более компактный формат выдачи информации;
• XML — более сложный формат по сравнению с JSON.

После отправки запроса вы получите ответ в формате JSON или XML. Что хорошо: ответ API будет содержать не только запрашиваемые данные, но и информацию об ошибках в формировании запросов.

Кстати, есть ещё формат данных — YAML. Он более ёмкий по сравнению с JSON и уж тем более по сравнению с XML.

Пример кода в JSON:

			{
    "sample" :{
        "property1":"value",
        "property2": 12,
        "property3": false,
        "arrayProperty":[
            "value1",
            "value2"
        ]
    }
}
		

XML:

			

    value
    12
    false
    
        value1
        value2
    

		

и YAML:

			sample:
  property1:'value'
  property2: 12
  property3: false
  arrayProperty: [value1, value2]
		

Основные виды API

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

REST

Архитектурный стиль, который использует обычные HTTP-методы для обмена данными. RESTful-сервисы много где используются в кодинге: всё просто, гибко и понятно. RESTful-сервисы хороши ещё и тем, что с помощью них можно работать и с JSON, и с XML. А это означает, что они особенно популярны у разработчиков.

SOAP

Протокол для обмена сообщениями между двумя сервисами. SOAP подчиняется строгим стандартам W3C и работает только с XML, а точнее с SOAP XML. Более надёжный и безопасный вид API, особенно для выполнении сложных программных транзакций, но требует больше времени и усилий за счёт того, что SOAP XML-ответы нужно правильно обрабатывать и анализировать.

GraphQL

Язык запросов от Нельзябука, альтернатива REST. GraphQL хорош тем, что он даёт возможность точечно запрашивать данные из API, увеличивает результативность запросов за счёт возможности извлечения только тех данных, которые действительно нужны. Плюс можно добавлять дополнительные поля в GraphQL без изменения серверной части.

WebSocket

Протокол бесперебойной отправки и получения сообщений между клиентом и сервером через одно соединение TCP. WebSocket можно пользоваться для работы чатов, игр и веб-сервисов, где важно отправлять сообщения и получать ответы в настоящем времени.

REST использует API для простых веб-приложений, SOAP — для сложных решений (особенно корпоративных), GraphQL хорош гибкостью получения данных, а WebSocket подойдёт для сервисов, где нужно в режиме реального времени обрабатывать запросы.

Принципы работы API

Как уже говорилось выше, API работает как посредник между сервисом и клиентом, позволяя им обмениваться необходимыми данными. API упрощает интеграцию сервисов и систем с помощью стандартизированного подхода к «общению» сервиса и клиента.

Как устроен запрос и ответ

Основные HTTP методы, которые используются для отправки запросов к API:

• GET используется для получения информации из базы данных сервера. Для открытия страницы сайта в браузере нужно получить все данные сайта и преобразовать их в «готовый» вид — по такому же принципу работает GET.
• POST для отправки новых данных на сервер. Например, несколько новых пользователей зарегистрировалось на сайте — POST автоматически отправляет все данные о новом реге на сервер.
• PUT для обновления уже занесённых данных. Например, пользователь уже был зарегистрирован на сайте, но решил сменить ник и заодно обновить аватарку. С помощью PUT все данные отправляются на сервер.
• DELETE для удаления данных. Та же аналогия: пользователь удалил информацию из раздела «Любимые фильмы» — эти данные стираются и с сервера.

Форматы данных

Форматов данных существует много. Два самых популярных формата — это JSON и XML.

JSON — более легковесный формат. Он проще для чтения и понимания человеком и понятнее для обработки машиной. Именно поэтому он и популярен.

			{
  "name": "John",
  "age": 30,
  "city": "New York"
}
		

XML — более сложный формат с большим количеством тегов. Используется в «формализованных» системах, в том числе и в корпоративных.

			
  John
  30
  New York

		

Как начать работать с API?

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

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

Для работы с API можно использовать разные специализированные инструменты, например, Postman и curl, которые автоматизируют процесс отправки запросов и получения ответов — при этом код писать не нужно.

Postman — это программа для тестирования API. Postman поддерживает разные форматы данных и методы HTTP. С помощью Postman можно настраивать параметры аутентификации и просматривать все полученные ответы.

Как работать с Postman:

• Откройте приложение Postman;
• Создайте новый запрос;
• Введите URL-адрес API;
• Укажите метод запроса;
• Добавьте API-ключ в заголовке запроса;
• Нажмите «Send» для отправки запроса.

curl — это командная строка для передачи данных, которая использует различные сетевые протоколы и пользуются API. Curl особенно часто используют для автоматизации задач или при работе с Linux.

Интеграция API в коде

После того, как тестирование запросов прошло успешно, можно переходить к интеграции API. Вот два примера интеграции — для Python и JavaScript.

Python:

			import requests
url = "https://api.openweathermap.org/data/2.5/weather"
params = {
    "q": "London",
    "appid": "ваш_ключ"
}
response = requests.get(url, params=params)
data = response.json()
print(f"Погода в Лондоне: {data['weather'][0]['description']}")
		

JavaScript:

			const fetch = require('node-fetch');
const url = 'https://api.openweathermap.org/data/2.5/weather?q=London&appid=ваш_ключ';
fetch(url)
  .then(response => response.json())
  .then(data => {
  })
  .catch(error => console.error('Ошибка:', error));
		

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

Практическое использование API

В этой части рассмотрим применение API на практике на примере запроса данных о погоде из публичного API и узнаем, как работать с токенами и авторизацией OAuth 2.0.

Пример запроса данных из публичного API

Возьмём пример запроса данных о погоде через OpenWeatherMap, сервис о погоде.

Шаги запроса:

• Регистрация на сайте OpenWeatherMap и получение API-ключа. Например, чтобы получить данные о текущей погоде в Москве, нужно составить запрос следующего вида: http://api.openweathermap.org/data/2.5/weather?q=Moscow&appid=ВАШ_API_КЛЮЧ

• Используя Python и библиотеку requests, можно отправить запрос следующим образом:

			import requests
city = "Moscow"
api_key = "ВАШ_API_КЛЮЧ"
url = f"http://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}"
response = requests.get(url)
data = response.json()
print(data)
		

• Ответ от сервера приходит в формате JSON.

Частичный пример ответа:

			{
    "weather": [
        {
            "description": "clear sky"
        }
    ],
    "main": {
        "temp": 280.32,
        "feels_like": 278.16,
        "temp_min": 279.15,
        "temp_max": 281.15
    },
    ...
}
		

Работа с токенами и OAuth 2.0

OAuth 2.0 — протокол авторизации, который даёт сторонним приложениям ограниченный доступ к данным пользователя без передачи пароля.

Как работать с OAuth 2.0:

• Создайте учетную запись разработчика;
• Зарегистрируйте ваше приложение на платформе, которая поддерживает OAuth 2.0;
• Предоставьте доступ к вашему приложению;
• После авторизации ваш сервер получает временный код, который затем обменивается на токен доступа:

			import requests
# Параметры приложения
client_id = 'ВАШ_CLIENT_ID'
redirect_uri = 'ВАША_REDIRECT_URI'
authorization_code = 'КОД_АВТОРИЗАЦИИ'
# Обмен кода на токен
token_url = 'https://authorization-server.com/token'
data = {
    'grant_type': 'authorization_code',
    'code': authorization_code,
    'redirect_uri': redirect_uri,
    'client_id': client_id,
    'client_secret': client_secret
}
response = requests.post(token_url, data=data)
tokens = response.json()
print(tokens)
		

Используя полученный токен доступа, ваше приложение может делать запросы к защищённым ресурсам пользователя.

Советы и лучшие практики

Чтение документации API

Знакомство с документацией API — это первый шаг в работе с API. Документация содержит все важные сведения о ресурсах, запросах и параметрах.

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

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

A FAQ поможет быстро решить типичные «стартовые» проблемы.

Обработка ошибок и исключений

Ошибки — основа работы с любым приложением, база. Если правильно обрабатывать ошибки, то вы как разработчик сможете лучше понимать, что происходит и на каком этапе, по какой причине была допущена ошибка.

Несколько советов по обработке ошибок и исключений:

• Проверка кодов состояния HTTP. Ошибка 200 или 404 — это и есть коды состояния HTTP. С помощью них можно быстрее понять, где именно затаилась проблема.
• Try-catch блоки. При работе с Python или JavaScript важно использовать try-catch блоки для поиска и устранения ошибок выполнения.
• Логирование ошибок и исключений с указанием времени их возникновения и деталей запроса поможет в анализе проблем.

Оптимизация запросов для минимизации нагрузки

Оптимизация запросов сильно снижает нагрузку на серверы и повышает производительность приложения. Базовые советы:

• Использовать кэширование ответов от серверов по максимуму — так вы избежите повторных реквестов к одному и тому же ресурсу и сократите время ожидания ответа.
• По возможности объединять несколько запросов в один для уменьшения количества сетевых обращений.
• Запрашивать только те данные, которые нужны в данный момент времени с помощью фильтрации.

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