Теория API
Клиент-серверная архитектура: клиент (мобильное приложение о погоде) – сервер (софт метеорологической станции). Расширенный вариант: клиент – балансировщик – кластер серверов (горячий/холодный резерв) – БД (база данных).
API – программный интерфейс приложения, обеспечивает взаимодействие между клиентом и сервером, предоставляется сервером.
Структура HTTP-запроса
URL. Уникальный адрес объекта, над которым нужно произвести действие.
Method. «Глагол» запроса, определяет действие. Основные методы:
GET (получить данные объекта),
POST (создать объект),
PUT (отредактировать объект),
DELETE (удалить объект).
Headers. «Заголовки» предоставляют метаинформацию о запросе, например:
User-Agent (тип устройства клиента),
Content-Type (формат данных в запросе),
Accept (формат данных, доступный для приёма).
Body. В «теле» запроса содержится информация, которую клиент передаёт серверу.
Структура HTTP-ответа
Status Code. Трёхзначный код состояния обработанного запроса. Например:
404 (объект не найден),
200 (успешно),
503 (сайт/API временно не работает).
Headers. Аналогично запросу.
Body. Аналогично запросу.
URL в запросе состоит из двух частей:
базовый URL (https://petstore.swagger.io);
путь (/v2/store/inventory).
Базовый URL включает:
протокол (http или https);
хост (доменное имя или IP);
порт (для http по умолчанию неявно указан :80, для https – :443; если используется другой порт, его нужно указать явно).
Path-параметр позволяет получить определённый объект и его характеристики. Добавляется в URL через «:», например – https://petstore.swagger.io/v2/pet/:id.
Query-параметр позволяет искать, фильтровать, сортировать данные. Чаще всего используется в GET. Добавляется в URL через «?». Несколько параметров отделяются друг от друга с помощью «&». Формат «имя=параметр». Например – https://petstore.swagger.io/v2/pet/findByStatus?status=available. Пример пагинации с помощью query-параметра – https://petstore.swagger.io/v2/pet/findByStatus?page=2&size=200.
Формат данных JSON на основе JS. Данные состоят из двух частей: key (ключ, атрибут объекта) и value (значение атрибута). Синтаксис: { "key": "value" }.
Формат данных XML (расширяемый язык разметки). Основной блок – node (узел). Структурно узел стоит из открывающего и закрывающего атрибута, между которыми располагается значение. Синтаксис: <atribut>znachenie</atribut>.
Примеры схем аутентификации в API
Базовая аутентификация. Клиент передает логин+пароль пользователя в заголовке Authorization.
API Key Auth. Клиент передаёт серверу уникальный ключ, который может быть включён в URL или Body.
OAuth 1/2 (открытая авторизация). Клиент и сервер автоматически обмениваются ключами, в итоге клиент получает токен доступа.
Last updated