API для чайников: обучение работе с AP

3 min read
API for dummies

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

API-интерфейсы существуют повсюду. Они лежат в основе практически всех взаимодействий с вашими устройствами и программным обеспечением. Например, приложения на вашем телефоне используют API для получения данных со своих серверов, а затем полагаются на отдельные API, предоставляемые iOS и Android, чтобы вывести эти данные на экран, отправить их вам с помощью push-уведомлений или поделиться ими с контактом.

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

Что такое API?

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

 

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

API определяет эти требования: можно указать, что клиентское приложение должно выполнить HTTP POST-запрос по адресу example.com/users; необходимо указать поля данных Name, Email и Password; в ответ будет выдано JSON-тело, содержащее идентификатор нового пользователя. Получив эту информацию, разработчики могут использовать API для успешной регистрации новых пользователей.

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

Почему API так важны?

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

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

Например, веб-скрапинг — сложная задача. Чтобы реализовать эффективный парсер, разработчикам необходимо создать сложную логику управления экземпляром браузера, а также задать настройки геолокационных прокси и обхода CAPTCHA. Выбрав API, можно получить доступ ко всей этой функциональности с помощью нескольких сетевых запросов. Затем вы можете использовать другие API для манипулирования полученными данными, их анализа и отправки результатов члену команды в вашей чат-платформе.

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

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

Типы API

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

 

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

Рассмотрим различные типы API:

#REST

Передача репрезентативного состояния (REST) была впервые теоретически обоснована Роем Филдингом в 2000 году и в настоящее время используется в большинстве веб-сервисов.

REST представляет данные системы в виде ресурсов без статического состояния, которые отображаются по HTTP-адресам. Для получения ресурсов и выполнения действий над ними используются HTTP-методы (GET, POST, PUT и DELETE).

Например, GET-запрос к example.com/users/100 должен вернуть следующую информацию о пользователе с ID 100:


{
    "Id": 100,
    "Name": "Example User",
    "Email": "[email protected]"
}

При последующем запросе DELETE на тот же URL сервис должен уничтожить объект.

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

#SOAP

В отличие от REST, Simple Object Access Protocol (SOAP) является формальной спецификацией для обмена данными. Все обмены SOAP используют формат данных XML, в то время как REST API могут предлагать JSON, XML, CSV или альтернативные варианты, специфичные для конкретной платформы. Простой вызов SOAP API может дать такой ответ:

xml
<?xml version="1.0" ?>
<soap:Envelope
   	 xmlns:soap="https://www.w3.org/2003/05/soap-envelope/"
   	 soap:encodingStyle="https://www.w3.org/2003/05/soap-encoding">
   	 <soap:Body>
   		 <m:GetUserResponse>
   			 <m:Id>100</m:Id>
   			 <m:Name>Example User</m:Name>
   			 <m:Email>[email protected]</m:Email>
   		 </m:GetUserResponse>
   	 </soap:Body>
</soap:Envelope>

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

#GraphQL

GraphQL — относительно молодая технология построения манипулируемых API. Она была разработана в компании Facebook в 2012 году и выложена в открытый доступ в 2015 году.

Язык GraphQL призван решить ряд проблем, связанных с API REST и SOAP. Он упрощает сложные запросы, предоставляя выразительный язык, который клиент может использовать для извлечения данных из API. GraphQL позволяет извлекать только конкретные поля данных вместо того, чтобы всегда предоставлять целые объекты. Это позволяет избежать бесполезной передачи избыточных данных.

Вот простой GraphQL-запрос для получения адреса электронной почты пользователя:

{
    user {
   	 Email
    }
}

Этот запрос даст следующий ответ:

json
{
    "user": {
   	 "Email": "[email protected]"
    }
}

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

 

#RPC

Удаленный вызов процедур (RPC) представляют собой простую форму API. Этот метод подразумевает вызов удаленной функции так, как если бы она была доступна локально. Основной сетевой запрос заставляет сервер API выполнить задачу и предоставить результат. Клиенту не известны подробности сетевого взаимодействия.

API RPC похож на интерфейсы функционального программирования. И глагол, и существительное будут включены в вызываемый URL — например, example.com/deleteUser?User=100. Это отличает его от REST, где глагол применяется к конкретному существительному (DELETE example.com/users/100). RPC непосредственно сопоставляется с кодом, в то время как REST пытается смоделировать структуру данных.

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

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

Системные API

API REST, SOAP, GraphQL и RPC используются в контексте сетевого взаимодействия между системами. Другие API применяются для различных видов интеграции, например, для системных интерфейсов, позволяющих приложениям получать доступ к функциям устройства.

Эти API предоставляются такими операционными системами, как Windows, Android и iOS. Они раскрываются в программных фреймворках и SDK, которые разработчики могут вызывать из своего кода. Системные API обеспечивают удобный доступ к таким функциям, как уведомления, значки пусковой установки, воспроизведение мультимедиа и доступ к датчикам устройства, не требуя от программистов написания низкоуровневого кода.

API языков программирования

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

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

Синхронные и асинхронные API

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

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

Подробный обзор: как работают API

Каждый из распространенных типов API имеет свою собственную грамматику. Например, REST работает с объектами и глаголами, а GraphQL предлагает более универсальное решение, ориентированное на клиента, а не на сервер. Давайте рассмотрим эти два варианта более подробно:

# REST

Для выполнения действий над ресурсами в REST используются глаголы методов HTTP. Наиболее распространенными методами являются GET, POST, PUT и DELETE:

GET /users/100 возвращает идентификатор пользователя 100.

POST /users создает нового пользователя.

PUT /users/100 обновляет пользователя по ID.

DELETE /users/100 удаляет пользователя по ID.

Эти примеры иллюстрируют основной синтаксис REST. В URL-адресе указывается ID объекта, с которым осуществляется взаимодействие, и множественное число существительного, экземпляром которого он является. Метод HTTP, используемый клиентом, определяет действие, которое будет выполнено.

Если для выполнения действия требуются дополнительные данные, они передаются в качестве полезной нагрузки HTTP-запроса. Например, при создании пользователя с помощью POST /users тело запроса будет содержать имя пользователя и пароль.

API отвечает на каждый запрос кодом состояния HTTP, характеризующим его результат. Например, ответ 404 Not Found на запрос GET /users/100 означает, что пользователя с идентификатором 100 не существует, а 202 Accepted на DELETE /users/100 означает, что пользователь успешно удален.

#GraphQL

Для сравнения, GraphQL представляет собой иной подход к API. Он рекламируется как [«язык запросов для вашего API»] (https://graphql.org), что намекает на более широкие функциональные возможности, которые он поддерживает. В то время как REST часто расходует пропускную способность, включая ненужные свойства объектов, GraphQL позволяет запрашивать именно те данные, которые вам нужны.

API, использующие GraphQL, создаются в виде сервисов, которые определяют конечные точки, к которым могут обращаться клиенты. Сервис представляет собой типизированную схему для сущности. Каждое поле в схеме имеет определенный тип данных:

type Team {
    id: ID
    name: String
}

type User {
    id: ID
    name: String
    email: String
    team: Team
}

Получить данные из схем можно с помощью запросов:

{
    user(id: 100) {
   	 email,
   	 team {
   		 name
   	 }
    }
}

Этот пример запроса может вернуть следующие данные:

{
    "email": "[email protected]",
    "team": "Example Team"
}

Поля в запросе поддерживаются резольверами. Когда запрос выполняется, резольверы отвечают за получение значения для каждого поля. В предыдущем примере резольвер team извлекает свойство name из команды, назначенной запрашиваемому пользователю, вместо того чтобы возвращать весь объект.

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

API GraphQL обычно создаются путем добавления в проект клиентской библиотеки GraphQL. Эти инструменты позволяют удобно генерировать схемы GraphQL из существующих ORM-моделей и другого кода.

Как интегрировать API

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

Типичная интеграция API включает в себя следующие этапы:

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

 

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

 

3. Найдите клиентскую библиотеку API для вашего языка программирования: Интеграция API может осуществляться путем прямых сетевых запросов с использованием библиотеки HTTP вашего языка программирования. Однако многие производители API также предлагают клиентские библиотеки и SDK, которые оборачиваются вокруг API и обеспечивают более удобный язык программирования. Выбор в пользу клиентской библиотеки еще больше упростит вашу реализацию и оградит от внесения каких-либо изменений в базовый API.

 

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

 

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

 

Важно также учитывать последствия интеграции API для безопасности. Хотя сторонние API могут упростить ключевые задачи разработки, при передаче пользовательских данных во внешнюю службу следует проявлять осторожность. Сможет ли платформа соответствовать тем же стандартам безопасности, что и ваша собственная? Если вы можете легко воспроизвести функциональность API, то безопаснее будет создать собственную реализацию в своем приложении.

Пример реального API

Готовы ли вы использовать API? Для быстрых экспериментов с веб-интерфейсами можно использовать уже имеющиеся на вашем компьютере HTTP-инструменты, в том числе curl и wget. Если же вы предпочитаете графические интерфейсы, то хорошей альтернативой будет Postman.

Получение поддельных данных с помощью программы Faker

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

Faker API использует принципы REST, при этом существительное в конце URL-адреса определяет тип генерируемых данных:

$ curl https://fakerapi.it/api/v1/books?_quantity=1
{
	"status": "OK",
	"code": 200,
	"total": 1,
	"data": [
    	{
        	"id": 1,
        	"title": "Duck and a pair of.",
        	"author": "Jessyca McKenzie",
        	"genre": "Sit",
        	"description": "ALL RETURNED FROM HIM TO YOU,\"' said Alice. 'I wonder how many miles I've fallen by this time, as it can be,' said the Cat. '--so long as I used--and I don't take this child away with me,' thought.",
        	"isbn": "9796054956226",
        	"image": "http://placeimg.com/480/640/any",
        	"published": "2010-09-14",
        	"publisher": "Quod Enim"
    	}
	]
}

Парсинг списков поисковых систем с помощью Bright Data

Bright Data предоставляет полный набор SERP API и proxy API. Это коммерческая платформа, которая требует регистрации:

 

Скриншот целевой страницы Bright Data SERP API

Чтобы начать использовать его, зарегистрируйтесь в бесплатной пробной версии, а затем, следуя документации, добавьте SERP API в свою учетную запись. Затем необходимо включить асинхронный режим в расширенных настройках API:

 

Прокси-инфраструктура веб-парсинга
Прокси-инфраструктура веб-парсинга

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

$ curl -i "https://brightdata.com/api/serp/req?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {API_TOKEN}" \
    -d '{"country":"us","query":{"q":"apis"}}'
...
x-response-id: s3wt2t...

Сгенерируйте API-токен в настройках учетной записи, а затем подставьте его в команду вместо `{API_TOKEN}`:

Генерация API-токена в Bright Data

Соответствующие значения других заполнителей для вашей учетной записи, {CUSTOMER_ID} и {CUSTOMER_ZONE}, вы можете найти на игровой площадке SERP API.

Данный пример запроса использует API для планирования поиска apis в Google в США. Скопируйте значение заголовка ответа x-response-id, отображаемое в выводе команды. Это значение можно использовать для получения результата SERP после его генерации. Подождите минуту и затем выполните следующий запрос:

$ curl "https://brightdata.com/api/serp/get_result?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}&output=json&response_id={RESPONSE_ID}"

Замените RESPONSE_ID на скопированное ранее значение. Данные, полученные в результате поиска, будут отображены в консоли.

Эти конечные точки являются примером RPC API. Если API является RESTful, то URL будут выглядеть следующим образом:

POST /api/serp/request and GET /api/serp/results/{RESPONSE_ID}.

Резюме

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

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

API упрощают реализацию специализированной функциональности в ваших системах. Вы можете позволить специалистам отрасли сделать за вас всю сложную работу, а затем подключить их платформы к своему коду. Попробуйте эффективную связку SERP API и proxy API компании Bright Data для решения задач по веб-скрапингу.