> For the complete documentation index, see [llms.txt](https://daymonri.gitbook.io/techwritersummary/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://daymonri.gitbook.io/techwritersummary/api/teoriya-api.md).

# Теория API

**Клиент-серверная архитектура:** клиент (мобильное приложение о погоде) – сервер (софт метеорологической станции). Расширенный вариант: клиент – балансировщик – кластер серверов (горячий/холодный резерв) – БД (база данных).

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

{% hint style="info" %}
Протокол передачи гипертекста **HTTP** лежит в основе API. **HTTP**-запрос основан на концепции, которая называется цикл запрос-ответ (request-respons).
{% endhint %}

### **Структура 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** (открытая авторизация). Клиент и сервер автоматически обмениваются ключами, в итоге клиент получает токен доступа.