Разбираемся с API: 10 концепций с примерами

От /

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

В этой статье мы расскажем об API, объяснив основные концепции и практики, которые вы можете применить в своей работе.

Содержание

Что такое API?

API расшифровывается как «Application Programming Interface» и переводится на русский как «программный интерфейс приложения» или «прикладной программный интерфейс». Это структура, состоящая из ряда команд, функций и протоколов, которые обеспечивают взаимодействие между различными приложениями. Ее основная цель — определить методы и структуры данных, которые разработчики могут использовать для взаимодействия с программными компонентами.

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

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

Виды API

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

Публичные или открытые API

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

Найти такие публичные API можно, например, на платформе Some Random API. Там есть множество конечных точек API, которые можно свободно использовать.

Внутренние или приватные API

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

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

Партнерские API

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

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

REST API

REST расшифровывается как «Representational State Transfer». Это можно перевести как «передача репрезентативного состояния» или «передача «самоописываемого» состояния».

REST или RESTful API — это правила построения веб-приложений и взаимодействия с веб-приложениями. Они опираются на стандартные методы и протоколы HTTP для обеспечения связи между клиентами и серверами.

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

Принципы REST API

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

Отсутствие состояния

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

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

Клиент-серверная архитектура

В REST API клиент и сервер — это отдельные компоненты, которые взаимодействуют через запросы и ответы. Клиент управляет пользовательским интерфейсом и пользовательским опытом, а сервер — хранением данных.

Унифицированный интерфейс

REST API получают доступ к ресурсам единообразно. Для доступа к ресурсам и манипулирования ими с помощью URI (Uniform Resource Identifier) используются такие HTTP-методы, как GET, POST, PUT и DELETE. Это делает REST API более понятными и доступными, поскольку разработчики могут опираться на знакомые им шаблоны.

Кэшируемость

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

RESTful API имеют отличную структуру, широко используемую в современном цикле разработки.

SOAP API

SOAP API расшифровывается как «Simple Object Access Protocol» и переводится как «простой протокол доступа к объектам». Это протокол для обмена структурированной информацией в веб-приложениях. В отличие от REST, который использует простые методы HTTP, SOAP использует XML для форматирования сообщений и имеет более сложную структуру.

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

Различия между REST и SOAP

REST и SOAP оба используются в Интернете, но при этом отличаются по архитектуре, стандартам и т. д. Вот некоторые из их различий:

  • Протокол vs.архитектурный стиль. SOAP — это протокол со стандартами и правилами. А REST —архитектурный стиль, использующий стандартные методы и протоколы HTTP для взаимодействия между веб-приложениями и с данными.
  • Формат сообщений. SOAP для форматирования сообщений использует XML, а REST — JSON, но также может использовать XML, HTML или обычный текст.
  • Сложность. SOAP более сложный из-за своих стандартов и обмена сообщениями в формате XML. REST проще и гибче, его легче реализовать.
  • Транспорт. SOAP может использовать различные протоколы (HTTP, SMTP и т. д.). REST обычно использует HTTPS.

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

JSON и XML

JSON (JavaScript Object Notation — «запись объектов JavaScript») и XML (eXtensible Markup Language — «расширяемый язык разметки») — это стандартные форматы данных для взаимодействия с API. Эти форматы служат одной и той же основной цели: кодировать структуры данных, передаваемых между сервером и клиентом, таким образом, чтобы они были понятны обоим.

JSON — это легкий формат обмена данными, созданный на основе JavaScript. Людям его легко читать и писать, а машинам — разбирать и генерировать.

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

Различия между JSON и XML

  • Удобство чтения. Синтаксис JSON более читабелен. Он идеален для быстрого взаимодействия и более доступен для разработчиков. XML имеет более сложный синтаксис. Он лучше всего подходит для представления сложных структур данных и документов.
  • Размер. JSON более компактный и легкий. Он обеспечивает более быструю передачу данных и меньшую пропускную способность. XML более объемный из-за использования тегов разметки.
  • Типы данных. JSON поддерживает такие типы данных, как строки, числа, массивы и объекты. В XML все данные записываются в текстовом виде, что требует парсинга для определенных типов данных.
  • Парсинг и производительность. JSON быстрее разбирается, особенно в среде JavaScript, благодаря совместимости. XML разбирается и обрабатывается медленнее, требует больше ресурсов.
  • Поддержка схем. Схемы JSON доступны, но не так обширны, как схемы XML. XML-схема очень эффективна для проверки структуры документа и типов данных.

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

Использование JSON и XML

Порой в качестве формата данных лучше использовать JSON, а в других случаях стоит отдать предпочтение XML. Знать, когда и где их использовать, очень важно.

JSON можно использовать, когда:

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

Вы можете использовать XML, когда:

  • Собираетесь работать со сложными структурами данных
  • Необходима валидация формата и структуры данных
  • Предполагается работа с приложениями, требующими обширных метаданных и описательных данных
  • Обмен данными должен быть в высшей степени расширяемым и самоописывающимся

Конечные точки API

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

Конечная точка позволяет API взаимодействовать с приложением, над которым вы работаете, обеспечивая связь и обмен информацией. Для доступа к ним используются такие методы HTTP, как GET, POST, PUT и DELETE, которые определяют тип выполняемой операции.

Примеры конечных точек API

Рассмотрим пример REST API для управления информацией о студентах в веб-приложении. Базовый URL для API может быть https://api.example.com. Теперь давайте рассмотрим возможные конечные точки.

Получение списка студентов

  • Конечная точка: https://api.example.com/students
  • Метод HTTP: GET
  • Назначение: Получение списка всех студентов, зарегистрированных в системе.

Запрос: GET https://api.example.com/students

Полученный ответ:

[
  {
    "id": 1,
    "name": "Opemipo Disu",
    "email": "opemipo.disu@school.com"
  },
  {
    "id": 2,
    "name": "Ralf Endrick",
    "email": "ralf.endrick@school.com"
  }
]

В этом примере мы использовали метод GET для получения информации из системы. Данные, которые мы запросили у конечной точки, возвращаются в формате JSON.

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

Добавление нового студента

  • Конечная точка: https://api.example.com/students
  • Метод HTTP: POST
  • Назначение: Добавление нового студента в систему управления.

Запрос:

POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}

Ответ:

{
  "id": 1,
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}

В данном случае мы работаем с конечной точкой https://api.example.com/students, потому что хотим добавить нового студента в систему. Использование этого эндпоинта — единственный способ получить доступ к пользователям.

Теперь давайте подумаем об удалении информации о конкретном студенте.

Удаление информации о студенте

  • Конечная точка: https://api.example.com/students/{id}
  • HTTP-метод: DELETE
  • Назначение: Удаление студента по его ID.

Запрос: DELETE https://api.example.com/students/1

Ответ:

{
  "message": "Student deleted successfully."
}

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

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

HTTP-методы

Методы HTTP определяют действия, выполняемые над ресурсами, определенными конечными точками API. У нас есть почти 40 зарегистрированных HTTP-методов, но наиболее распространенными являются четыре из них: GET, POST, PUT и DELETE.

Давайте рассмотрим, для чего используются эти методы.

GET

Метод GET позволяет получить данные с сервера, не внося в них никаких изменений.

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

Запрос: GET https://api.example.com/students

Ответ:

[
  {
    "id": 1,
    "name": "Opemipo Disu",
    "email": "opemipo.disu@school.com"
  },
  {
    "id": 2,
    "name": "Ralf Endrick",
    "email": "ralf.endrick@school.com"
  }
]

Здесь мы использовали метод GET для получения из конечной точки API данных, представленных в формате JSON.

POST

Метод POST отправляет данные на сервер для создания нового ресурса. В отличие от GET, который используется для получения данных, POST отправляет данные на сервер. GET зависит от данных, отправленных на сервер методом POST.

Мы уже видели работу метода POST на примере с регистрацией студента. На случай, если вы его пропустили, давайте повторим.

Запрос:

POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}

Мы отправили запрос, используя метод POST, чтобы добавить информацию о студенте на сервер.

Вот полученный ответ:

{
  "id": 1,
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}

Видим, что метод POST помог создать и зарегистрировать нового студента. Именно так он и работает.

PUT

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

Давайте рассмотрим пример обновления информации о студенте с помощью метода PUT.

Запрос:

PUT https://api.example.com/students/1
Content-Type: application/json

{
  "name": "Opemipo Hay",
  "email": "opemipo.hay@student.com"
}

Ответ:

{
  "id": 1,
  "name": "Opemipo Hay",
  "email": "opemipo.hay@student.com"
}

Здесь нам нужно указать, какую конкретно информацию мы хотим обновить, поэтому мы ссылаемся на ID, а затем добавляем данные, которые нужно изменить.

DELETE

Этот метод используется для удаления существующих ресурсов. Когда выполняется запрос DELETE, сервер удаляет ресурс, на который указывает URI.

Для примера рассмотрим удаление информации о студенте по его ID.

Запрос: DELETE https://api.example.com/students/1

Ответ:

{
  "message": "Student's information deleted successfully"
}

В запросе мы использовали метод DELETE для удаления информации о пользователе по его ID. После этого мы получили ответ: «Student’s information deleted successfully» («Информация о студенте успешно удалена»).

Коды состояния HTTP

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

Из множества кодов состояния HTTP можно выделить наиболее распространенные: 200, 400, 500.

200 (OK)

Если вы получаете такой ответ, значит, запрос выполнен успешно, и сервер возвращает запрошенные данные.

Сервер может послать такой код состояния, например, при успешном GET-запросе для получения данных. Когда вы видите этот код на вкладке «Network» консоли разработчика, это означает, что операция прошла успешно и сервер обработал запрос так, как ожидалось.

400 (Not Found)

Вы получаете этот ответ, когда сервер не может найти запрошенный ресурс или данные. Так бывает, если данные были получены неправильно или ресурс не существует.

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

Запрос: GET https://api.example.com/users/583

Ответ:

{
  "status": 404,
  "message": "Resource not found"
}

В ответе мы получим ошибку, так как в предполагаемой конечной точке нет ресурса.

500 (Internal Server Error)

Такой ответ означает, что сервер столкнулся с непредвиденной ситуацией, которая не позволила ему выполнить запрос.

Вы можете получить этот ответ, если при обработке запроса произошла ошибка на стороне сервера.

Запрос:

POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo",
  "email": "opemipo.disu@example.com"
}

Ответ:

{
  "status": 500,
  "message": "Internal server error"
}

500 Internal Server Error указывает на общую ошибку на стороне сервера. Это сигнал о том, что на сервере что-то пошло не так, и не обязательно из-за запроса клиента.

Конечно, есть и другие коды состояния HTTP. Ознакомиться с ними можно, например, в статье Википедии.

Аутентификация и авторизация

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

Авторизация определяет, к каким ресурсам или операциям разрешен доступ аутентифицированному субъекту.

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

Ключи API и OAuth

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

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

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

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

OAuth (Open Authorization) — это система аутентификации на основе токенов, которая позволяет сторонним приложениям получать доступ к данным пользователя без раскрытия его учетных данных.

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

Роль аутентификации в обеспечении безопасности API

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

Ограничение скорости и троттлинг

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

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

Чтобы управлять ограничениями скорости, приложения должны постепенно увеличивать время ожидания между повторными попытками при достижении предела.

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

Тестирование API

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

Инструменты для тестирования API

Postman

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

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

cURL

Этот инструмент командной строки позволяет передавать данные с помощью URL-адресов. cURL используется в основном из-за своей доступности и гибкости. Он особенно популярен среди разработчиков, привыкших работать в командной строке.

Swagger

Swagger — это набор инструментов для документирования и тестирования API. Он позволяет визуализировать ресурсы API и взаимодействовать с ними с без ручного создания запросов.

Руководство по тестированию API

1. Определите конечную точку и метод.

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

Пример. Чтобы получить данные о пользователе, вы можете использовать запрос GET https://api.example.com/users.

2. Настройте запрос.

Откройте Postman, создайте новый запрос, введите URL конечной точки и выберите метод HTTP. Добавьте необходимые заголовки, например, ключи API и параметры.

Для GET-запроса на получение данных о пользователях просто установите URL на https://api.example.com/users и включите все необходимые заголовки и параметры.

3. Отправьте запрос.

Нажмите кнопку «Send» в Postman, чтобы выполнить запрос и просмотреть ответ.

4. Проанализируйте ответ.

  • Код состояния. Указывает на успех или неудачу запроса (например, 200 OK, 404 Not Found).
  • Заголовки. Предоставляют метаданные об ответе.
  • Тело. Содержит данные, возвращаемые API, обычно в формате JSON или XML.

Пример. Успешный GET-запрос может вернуть код состояния 200 и тело JSON с данными пользователя.

5. Обработайте ошибки

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

Пример. Код состояния 404 указывает на то, что конечная точка неверна или ресурс не существует.

Соответствующим образом исправьте запрос и повторите попытку.

6. Автоматизируйте тестирование

Postman поддерживает скрипты для автоматизации тестов. Вы можете написать скрипты предварительных запросов для задания условий и тестовые скрипты для проверки ответов.

Пример. Чтобы проверить успешный ответ, добавьте следующий скрипт на вкладке «Tests» Postman:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

Используя такие инструменты, как Postman, cURL и Swagger, вы можете упростить процесс тестирования API, обеспечив надежное и эффективное взаимодействие вашего приложения с внешними сервисами.

Заключение

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

В этой статье мы рассмотрели фундаментальные концепции API, включая их типы, ключевые принципы API REST и SOAP, форматы данных JSON и XML, конечные точки API и методы HTTP.

Кроме того, мы рассмотрели темы безопасности API, ограничения скорости и троттлинга.

Если вы нашли эту статью полезной, пожалуйста, оцените нас на GitHub.

Перевод статьи «Understanding APIs: 10 API Concepts and Examples».

Похожие записи

Оставьте комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Прокрутить вверх