Перейти к основному содержимому

API - интерфейсы прикладного программирования

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВНЕ ДЛЯ НОВИЧКОВВ РАЗРАБОТКЕ
Всем

API​

API​

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

Приложение А отправляет запросы в Приложение Б, получает на них ответы. Аналогично и Приложение Б шлёт запросы, получая ответы. Они оба общаются на едином языке и придерживаются определённых правил. Эти правила - API.

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

API обычно состоит из:

  • Точек доступа (endpoints, эндпоинты) — URL, по которым можно обращаться.
  • Методов HTTP — GET, POST, PUT, PATCH, DELETE и др.
  • Параметров запроса — пути, строка запроса (query string), заголовки, тело.
  • Формата данных — JSON, XML, Protobuf и т.д.
  • Документации — описание возможностей, примеры использования, ограничения.

Контракт интерфейса​

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

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

OpenAPI​

Что такое Open API​

OpenAPI — это стандарт для описания веб-API. Ранее стандарт назывался Swagger. Спецификация позволяет описать интерфейс в формате YAML или JSON.

image-31.jpg

Преимущества использования спецификации:

  • Автоматическая генерация документации
  • Создание клиентских библиотек для разных языков
  • Генерация серверного кода
  • Валидация запросов и ответов
  • Визуализация через инструменты вроде Swagger UI

Базовая структура документа в формате YAML:

openapi: 3.1.0
info:
  title: API для управления задачами
  description: Сервис для создания, чтения, обновления и удаления задач
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Продуктивный сервер
  - url: https://dev-api.example.com/v1
    description: Тестовый сервер

Описание путей и методов​

Раздел paths содержит описание всех доступных адресов и методов:

paths:
  /tasks:
    get:
      summary: Получить список всех задач
      description: Возвращает массив задач с возможностью фильтрации
      parameters:
        - name: status
          in: query
          description: Фильтр по статусу задачи
          required: false
          schema:
            type: string
            enum: [pending, completed, cancelled]
        - name: limit
          in: query
          description: Максимальное количество задач в ответе
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        '401':
          description: Неавторизованный доступ
    post:
      summary: Создать новую задачу
      description: Добавляет задачу в систему
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreate'
      responses:
        '201':
          description: Задача создана
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Некорректные данные
        '401':
          description: Неавторизованный доступ
  /tasks/{taskId}:
    get:
      summary: Получить задачу по идентификатору
      parameters:
        - name: taskId
          in: path
          description: Уникальный идентификатор задачи
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Задача найдена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Задача не найдена
    put:
      summary: Обновить задачу полностью
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskUpdate'
      responses:
        '200':
          description: Задача обновлена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Задача не найдена
    patch:
      summary: Частично обновить задачу
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskPatch'
      responses:
        '200':
          description: Задача обновлена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
    delete:
      summary: Удалить задачу
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Задача удалена
        '404':
          description: Задача не найдена

Описание схем данных​

Раздел components/schemas содержит определения моделей данных:

components:
  schemas:
    Task:
      type: object
      required:
        - id
        - title
        - status
        - createdAt
      properties:
        id:
          type: integer
          description: Уникальный идентификатор задачи
          example: 123
        title:
          type: string
          description: Заголовок задачи
          maxLength: 200
          example: "Подготовить отчет"
        description:
          type: string
          description: Подробное описание задачи
          nullable: true
          example: "Собрать данные за квартал и оформить презентацию"
        status:
          type: string
          description: Текущий статус задачи
          enum: [pending, completed, cancelled]
          example: "pending"
        priority:
          type: string
          description: Приоритет задачи
          enum: [low, medium, high]
          default: "medium"
          example: "high"
        dueDate:
          type: string
          format: date-time
          description: Срок выполнения задачи
          nullable: true
          example: "2026-03-15T18:00:00Z"
        createdAt:
          type: string
          format: date-time
          description: Дата и время создания задачи
          example: "2026-02-26T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          description: Дата и время последнего обновления
          nullable: true
          example: "2026-02-26T14:45:00Z"
    
    TaskCreate:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          maxLength: 200
        description:
          type: string
          nullable: true
        status:
          type: string
          enum: [pending, completed, cancelled]
          default: "pending"
        priority:
          type: string
          enum: [low, medium, high]
          default: "medium"
        dueDate:
          type: string
          format: date-time
          nullable: true
    
    TaskUpdate:
      type: object
      required:
        - title
        - description
        - status
        - priority
        - dueDate
      properties:
        title:
          type: string
          maxLength: 200
        description:
          type: string
          nullable: true
        status:
          type: string
          enum: [pending, completed, cancelled]
        priority:
          type: string
          enum: [low, medium, high]
        dueDate:
          type: string
          format: date-time
          nullable: true
    
    TaskPatch:
      type: object
      properties:
        title:
          type: string
          maxLength: 200
        description:
          type: string
          nullable: true
        status:
          type: string
          enum: [pending, completed, cancelled]
        priority:
          type: string
          enum: [low, medium, high]
        dueDate:
          type: string
          format: date-time
          nullable: true

Типы данных в схемах​

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

  • string — текстовая строка
  • integer — целое число
  • number — число с плавающей точкой
  • boolean — логическое значение
  • array — массив значений
  • object — объект с полями

Для строковых полей доступны форматы:

  • date — дата в формате YYYY-MM-DD
  • date-time — дата и время в формате ISO 8601
  • email — адрес электронной почты
  • uuid — универсальный уникальный идентификатор
  • uri — универсальный идентификатор ресурса

Обязательность полей​

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

Поле nullable: true разрешает передавать значение null для опциональных полей.

Ограничения значений​

Для числовых полей можно задать ограничения:

  • minimum — минимальное значение
  • maximum — максимальное значение
  • exclusiveMinimum — строгое ограничение снизу
  • exclusiveMaximum — строгое ограничение сверху

Для строковых полей:

  • minLength — минимальная длина строки
  • maxLength — максимальная длина строки
  • pattern — регулярное выражение для валидации

Для массивов:

  • minItems — минимальное количество элементов
  • maxItems — максимальное количество элементов
  • uniqueItems — требование уникальности элементов

Примеры данных​

Ключевое слово example или examples позволяет привести образцы данных. Это помогает понять формат запросов и ответов без дополнительных пояснений.

Коды ответов HTTP​

Стандартные коды состояния:

  • 200 — успешный запрос
  • 201 — ресурс создан
  • 204 — успешный запрос без тела ответа
  • 400 — некорректный запрос
  • 401 — неавторизованный доступ
  • 403 — запрещенный доступ
  • 404 — ресурс не найден
  • 409 — конфликт при создании или обновлении
  • 422 — ошибки валидации данных
  • 500 — внутренняя ошибка сервера

Версионирование API​

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

Способы указания версии:

В пути:

GET /v1/tasks
GET /v2/tasks

В заголовке:

GET /tasks
Accept: application/vnd.example.v1+json

В параметре запроса:

GET /tasks?version=1

Рекомендуемый подход — указание версии в пути. Это делает версию явной и упрощает маршрутизацию запросов.

Параметры запроса​

Параметры могут передаваться разными способами:

В пути (path):

GET /tasks/123

В строке запроса (query):

GET /tasks?status=pending&limit=10

В заголовках (header):

Authorization: Bearer token123

В теле запроса (body):

{
  "title": "Новая задача",
  "priority": "high"
}

Форматы содержимого​

Наиболее распространенные форматы:

  • application/json — данные в формате JSON
  • application/xml — данные в формате XML
  • multipart/form-data — передача файлов
  • application/x-www-form-urlencoded — форма в кодировке URL

Документирование​

Поля summary и description содержат краткое и подробное описание операции. Поле description поддерживает форматирование Markdown для создания структурированной документации.

Валидация данных​

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

Автоматизация​

На основе спецификации можно генерировать:

  • Документацию в формате HTML
  • Клиентские библиотеки для различных языков программирования
  • Серверный код с заглушками для обработчиков
  • Тесты для проверки соответствия реализации спецификации

SDK​

SDK (Software Development Kit) — это набор готовых библиотек, инструментов и примеров кода, предназначенных для работы с определённым API. Используется тогда, когда хочется не писать HTTP-запросы вручную, а использовать удобный интерфейс на своём языке.

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

REST​

Что такое REST?​

REST API (Representational State Transfer) является архитектурным стилем, использующем стандартные HTTP-методы. Это самый распространённый подход для реализации веб-сервисов - можно просто определить эндпоинт, методы, параметры, формат и разработать серверный бэкенд-код, который будет «принимать» запросы и «отвечать» на них. На стороне клиента проблем ещё меньше - там просто нужно, к примеру, сделать кнопку, которая будет формировать запрос и отправлять его по эндпоинту.

Он основан на следующих принципах:

  • Стандартные методы HTTP.
  • Ресурсо-ориентированная адресация (URL как ресурсы).
  • Отсутствие состояния (stateless).
  • Поддержка разных форматов данных (обычно JSON или XML).

REST (Representational State Transfer) — это архитектурный стиль для создания веб-сервисов, основанный на использовании HTTP-протокола. REST API предоставляет набор правил для взаимодействия между клиентом и сервером через стандартные HTTP-методы.

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

Каждый ресурс имеет уникальный URL (Uniform Resource Locator), а данные отправляются, как правило, в формате JSON или XML. Каждый запрос содержит всю необходимую информацию для его обработки. Сервер не хранит состояние клиента между запросами. Чуть позже мы углубимся в API и REST.

Документацией REST можно считать документацию HTTP.

Стандартные методы HTTP, используемые в REST:

  • GET — получение данных.
  • POST — создание нового ресурса.
  • PUT/PATCH — обновление существующего ресурса.
  • DELETE — удаление ресурса.

RESTful​

Приложение, следующее принципам REST, называется RESTful.

RESTful API представляет собой интерфейс для взаимодействия между клиентом и сервером через стандартные методы протокола HTTP. Каждый ресурс в системе имеет уникальный идентификатор — адрес (URL), по которому к нему можно обратиться.

Архитектура REST основана на шести ключевых принципах:

  • Клиент-серверная модель разделяет пользовательский интерфейс от обработки данных. Клиент отвечает за представление информации, сервер — за хранение и управление ресурсами. Такая декомпозиция упрощает разработку и масштабирование.
  • Отсутствие состояния означает, что каждый запрос от клиента к серверу содержит всю необходимую информацию для его обработки. Сервер не сохраняет контекст предыдущих запросов. Каждое взаимодействие автономно и независимо.
  • Кэширование позволяет клиенту или промежуточным прокси хранить ответы сервера для повторного использования. Это снижает нагрузку на сервер и ускоряет работу приложения. Ответы должны явно указывать, можно ли их кэшировать.
  • Единообразие интерфейса обеспечивает согласованный способ взаимодействия с ресурсами. Ресурсы идентифицируются через стандартные адреса, операции выполняются через стандартные методы, сообщения передаются в стандартных форматах.
  • Многоуровневая система позволяет строить архитектуру из нескольких слоев. Клиент взаимодействует с промежуточными серверами, которые могут выполнять функции балансировки нагрузки, безопасности или кэширования, не зная о конечном сервере.
  • Код по требованию является опциональным принципом. Сервер может передавать клиенту исполняемый код, расширяющий его функциональность. Этот принцип применяется редко в современных веб-API.

Создание REST API​

Как создать свой REST API?

  1. Определить, какие данные будут передаваться.
  2. Определить, какие операции нужно поддерживать (CRUD: Create, Read, Update, Delete).
  3. Определить, кто будет использовать API (фронтенд, мобильное приложение, другие сервисы).
  4. Выбрать и определить базовый путь, например, /api/v1.
  5. Для каждого типа данных определить URL-пути:
    • GET /users – получить список пользователей
    • GET /users/123 – получить пользователя с ID 123
    • POST /users – создать нового пользователя
    • PUT /users/123 – обновить пользователя
    • DELETE /users/123 – удалить пользователя
  6. Определить необходимость и добавить параметры запроса - фильтрация, сортировка, пагинация.
  7. Определить формат обмена данными (обычно JSON).
  8. Определить структуру запросов и ответов, к примеру:
// Пример запроса
{
  "name": "John",
  "email": "john@example.com"
}

// Пример ответа
{
  "id": 123,
  "name": "John",
  "created_at": "2025-04-05T10:00:00Z"
}

  1. Настроить маршруты (роутинг) - сопоставить URL + HTTP-метод → обработчик.
  2. В обработчиках нужно написать возможности:
    • чтения входящих данных из заголовков, строки запроса или тела;
    • проверку данных (валидацию);
    • обращение к БД или другому источнику данных (например, файл);
    • формирование ответа - статус, заголовки, тело;
    • обработка ошибок.

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

  1. Добавить авторизацию (если нужна, но очевидно она всегда нужна для безопасности) - JWT, OAuth, API ключи. По возможности, кстати, нужно придерживаться и иных мер безопасности - использование HTTPS, ограничение доступа по CORS, валидация данных и логирование действий.
  2. Задокументировать, указав описание всех эндпоинтов, примеры запросов и ответов, описание кодов и ошибок. Для этого можно использовать Open API / Swagger.
  3. Проверять работу всех методов можно через Postman, curl, Swagger UI.
  4. После тестирования, сервис разворачивается на бэкенд-сервере, допустим на хостинге, и когда будет определен хост, можно будет уже отправлять запросы. До этого момента, на этапе тестирования, его можно выполнять на локальной машине. Итого:
    • клиент отправляет HTTP-запрос на конкретный URL;
    • сервер определяет маршрут и вызывает функцию-обработчик;
    • обработчик получает данные, может взаимодействовать с БД или даже другими API;
    • сервер формирует HTTP-ответ и отправляет его обратно клиенту.

image.png

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

Другие API​

А как же другие API?

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

SOAP API более старый протокол с жёсткой структурой, основанный на XML. Его можно встретить в устаревших корпоративных системах.

gRPC API высокопроизводительный (ведь там RPC-протокол), работает поверх HTTP/2, использует Protobuf. В высоконагруженных системах с микросервисами можно часто встретить такой стиль.

WebSocket API, как мы уже не раз отметили, использует двустороннее постоянное соединение.

SSE (Server-Sent Events) использует одностороннюю передачу данных от сервера к клиенту - новости, уведомления, мониторинг.

OAuth 2.0 API — это протокол авторизации, который позволяет приложениям получать ограниченный доступ к ресурсам пользователя без необходимости знать его пароль. К примеру, это авторизация через Google/Facebook, подключение к Google Drive или Dropbox, работа с банковскими API. OAuth 2.0 использует токены , такие как:

  • access_token — временный ключ для доступа к ресурсам
  • refresh_token — для получения нового access_token

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

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

Кстати говоря о фронте, следует отметить, что как раз для работы с API в JavaScript используют метод fetch():

fetch('/api/user/profile', {
  method: 'GET',
  headers: { Authorization: 'Bearer <token>' }
})

fetch() — это встроенный в браузер метод , позволяющий отправлять HTTP-запросы к серверу и получать данные без перезагрузки страницы. Он возвращает Promise , который разрешается в объект ответа (Response), а затем можно обработать тело ответа (например, как JSON или текст). Синтаксис прост - fetch(input, init). input это URL, по которому делается запрос (строка) или объект Request, а init (необязательный) это объект с настройками запроса: метод, заголовки, тело и т.д.

После вызова fetch(), вы получаете объект Response.

Основные свойства Response:

  • .ok — возвращает true, если статус 200–299.
  • .status — HTTP-статус ответа (например, 200, 404).
  • .statusText — текстовое описание статуса (например, "OK", "Not Found").
  • .headers — объект Headers, содержащий заголовки ответа.
  • .url — фактический URL ответа (может отличаться от запрошенного при редиректах).

Методы для получения тела:

  • .json() — парсит тело как JSON.
  • .text() — возвращает тело как строку.
  • .blob() — возвращает как Blob (например, изображения).
  • .formData() — возвращает как FormData.
  • .arrayBuffer() — возвращает как массив ArrayBuffer.

fetch() подчиняется политике CORS (Cross-Origin Resource Sharing), если сервер не разрешает кросс-доменные запросы, браузер блокирует их, а для авторизации может потребоваться установка заголовков или использование credentials.

Web API — это общий термин, обозначающий API, доступные через веб-интерфейс. Это могут быть как серверные API (например, REST, GraphQL), так и клиентские API (например, браузерные API).

Основные типы Web API:

Серверные API :

  • RESTful API: стандартный подход к созданию веб-сервисов.
  • GraphQL API: гибкий запрос данных с возможностью выбора полей.
  • SOAP API: устаревший протокол для веб-сервисов.

Клиентские API :

  • DOM API: управление HTML-документами в браузере.
  • Fetch API: выполнение HTTP-запросов из браузера.
  • Geolocation API: получение географических данных пользователя.

Fluent API — это стиль программирования, при котором методы возвращают объект, позволяя «цеплять» вызовы методов друг за другом. Используется в ORM, билдерах SQL, тестовых фреймворках. Этот подход часто используется для создания удобного и читаемого кода.

FastAPI — это современный веб-фреймворк для создания API на Python. Он известен своей высокой производительностью, простотой использования и поддержкой асинхронного программирования. Основан на на Starlette и Pydantic, что делает его одним из самых быстрых фреймворков.

Чит-лист FastAPI - https://cheatsheets.zip/fastapi

Starlette — это лёгкий и быстрый веб-фреймворк для Python, предназначенный для создания асинхронных веб-приложений и API. Он является основой таких проектов, как FastAPI , и известен своей производительностью и гибкостью.

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

SignalR — это библиотека для ASP.NET Core, которая позволяет реализовать реальное взаимодействие между клиентом и сервером. Она поддерживает двустороннюю связь через WebSocket, Server-Sent Events (SSE) и Long Polling. Именно оно используется для чатов, онлайн-игр, обновлений.

Long Polling — это техника для реализации асинхронного взаимодействия между клиентом и сервером в веб-приложениях. Она позволяет клиенту ожидать новые данные от сервера, не отправляя постоянные запросы.

Как работает:

  • Клиент отправляет HTTP-запрос на сервер.
  • Сервер держит соединение открытым до тех пор, пока не появятся новые данные или истечет таймаут.
  • Как только данные доступны, сервер отправляет ответ, и клиент сразу же отправляет новый запрос.

Каждая программа, которая поддерживает какой-то свой метод взаимодействия, может предоставлять свой интерфейс, и как правило, он будет характерен именно для взаимодействия соответствующего продукта - Kubernetes API, Telegram API, Windows API, WhatsApp API, Google Maps API, Twitter/X API и прочие.

Освоение главы0%