🔄 Что такое API?

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

API (Application Programming Interface) — это набор правил и протоколов, которые позволяют различным программам обмениваться данными и функциями. Простыми словами: API — это “розетка” для подключения одной программы к другой.

🌐 REST API — современный стандарт веб-взаимодействия

REST (Representational State Transfer) — это архитектурный стиль для создания веб-сервисов, предложенный Роем Филдингом в 2000 году. Это не протокол или формат, а набор принципов и ограничений.

Основные принципы REST

1. Клиент-серверная архитектура — разделение ответственности
2. Отсутствие состояния (Statelessness) — каждый запрос содержит всю необходимую информацию
3. Кэширование — ответы могут быть помечены как кэшируемые
4. Единый интерфейс — стандартный способ взаимодействия
5. Многоуровневая система — между клиентом и сервером могут быть промежуточные слои
6. Код по запросу (опционально) — сервер может передавать исполняемый код

📊 Ресурсы и URI

В REST API всё является ресурсом, который идентифицируется с помощью URI (Uniform Resource Identifier):

• /users — коллекция пользователей
• /users/123 — конкретный пользователь
• /users/123/posts — посты конкретного пользователя

Хорошие практики проектирования URI

• Используйте существительные для ресурсов
• Применяйте множественное число для коллекций
• Используйте иерархию для связанных ресурсов
• Избегайте глаголов в URI
• Используйте дефисы (-) вместо подчеркиваний (_)

Хорошо: /articles/123/comments Плохо: /getArticleComments?article_id=123

🔄 HTTP методы в REST API

REST использует стандартные HTTP методы для операций с ресурсами:

Примеры использования методов

• GET /users — получить список пользователей
• GET /users/123 — получить информацию о пользователе с ID 123
• POST /users — создать нового пользователя
• PUT /users/123 — полностью обновить данные пользователя
• PATCH /users/123 — обновить отдельные поля пользователя
• DELETE /users/123 — удалить пользователя

🔢 HTTP статус-коды в REST API

REST использует стандартные HTTP статус-коды для указания результата операции:

Успешные операции

• 200 OK — запрос выполнен успешно
• 201 Created — ресурс успешно создан
• 204 No Content — успешный запрос без тела ответа

Ошибки клиента

• 400 Bad Request — неверный запрос
• 401 Unauthorized — необходима аутентификация
• 403 Forbidden — доступ запрещен
• 404 Not Found — ресурс не найден
• 405 Method Not Allowed — метод не разрешен для данного ресурса
• 422 Unprocessable Entity — невозможно обработать данные

Ошибки сервера

• 500 Internal Server Error — внутренняя ошибка сервера
• 502 Bad Gateway — ошибка шлюза
• 503 Service Unavailable — сервис временно недоступен

📋 Форматы данных в REST API

REST не привязан к конкретному формату данных, но наиболее распространены:

JSON (JavaScript Object Notation)

1
2
3
4
5
6
7

{
  "id": 123,
  "name": "Иван Иванов",
  "email": "ivan@example.com",
  "roles": ["user", "admin"],
  "active": true
}

XML (eXtensible Markup Language)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<user>
  <id>123</id>
  <name>Иван Иванов</name>
  <email>ivan@example.com</email>
  <roles>
    <role>user</role>
    <role>admin</role>
  </roles>
  <active>true</active>
</user>

Почему JSON популярнее?

• Более компактный формат
• Легче читается человеком
• Проще парсится в JavaScript
• Меньше избыточности

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

Основные способы аутентификации

1. Basic Authentication — логин и пароль в заголовке Authorization
2. API ключи — уникальные ключи в URL или заголовке
3. OAuth 2.0 — делегирование доступа без передачи учетных данных
4. JWT (JSON Web Tokens) — подписанные токены с информацией о пользователе
5. OpenID Connect — надстройка над OAuth 2.0 для аутентификации

1

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

👨‍💻 Версионирование API

Версионирование помогает вносить изменения в API без нарушения работы существующих клиентов.

Способы версионирования

• В URL: /api/v1/users
• В заголовке: Accept: application/vnd.company.api+json;version=1
• В параметре запроса: /api/users?version=1
• В поддомене: v1.api.example.com/users

🔧 Документирование REST API

Хорошая документация критически важна для API:

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

• Swagger/OpenAPI — стандарт для описания RESTful API
• Postman — создание, тестирование и документирование API
• RAML — язык разметки для API
• API Blueprint — язык описания API на основе Markdown

Что должна включать документация

• Описание всех эндпоинтов
• HTTP методы
• Параметры запросов
• Форматы ответов
• Коды состояний
• Примеры запросов и ответов
• Информация об аутентификации

⚡ GraphQL — альтернатива REST

GraphQL — язык запросов API, разработанный Facebook. Основные отличия от REST:

• Клиент указывает точно, какие данные ему нужны
• Один эндпоинт для всех запросов
• Строгая типизация данных
• Минимизация избыточных данных
• Возможность объединения нескольких запросов

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

query {
  user(id: 123) {
    name
    email
    posts {
      title
      createdAt
    }
  }
}

🚀 Как тестировать API?

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

• Postman — популярный инструмент для работы с API
• curl — консольная утилита для отправки HTTP-запросов
• Insomnia — удобный клиент REST
• Автоматизированное тестирование — Jest, Mocha, JUnit и т.д.

Пример запроса с curl

1
2
3

curl -X GET https://api.example.com/users/123 \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json"

🛠️ Практические рекомендации

• Используйте HTTPS для всех API
• Добавляйте валидацию входных данных
• Ограничивайте скорость запросов (Rate limiting)
• Добавляйте пагинацию для больших коллекций
• Включайте информативные сообщения об ошибках
• Используйте сжатие данных (Gzip, Brotli)
• Добавляйте кэширование с помощью заголовков

📚 Что дальше?

• Узнайте про CDN
• Изучите микросервисную архитектуру
• Погрузитесь в серверную разработку