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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://daymonri.gitbook.io/techwritersummary/api/teoriya-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.