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

# API

<mark style="color:orange;">**API**</mark> (Application Programming Interface) — это интерфейс программирования приложений, который позволяет различным программам или системам взаимодействовать между собой. API предоставляет набор правил, протоколов и инструментов для создания программного обеспечения. Оно позволяет одному приложению получить доступ к функциональности другого приложения или системы через предопределенные методы.

#### Основные концепции API

1. **Клиент и сервер**
   * **Клиент**: Приложение, которое делает запросы к API, чтобы получить данные или выполнить действия. Это может быть веб-приложение, мобильное приложение или любое другое программное обеспечение.
   * **Сервер**: Приложение или сервис, который принимает запросы от клиентов через API, обрабатывает их и отправляет ответы.
2. **Запросы и ответы**
   * **Запрос (Request)**: Клиент отправляет запрос серверу для выполнения определенного действия. Запрос обычно состоит из:
     * **Метода HTTP**: Указывает тип действия (GET, POST, PUT, DELETE).
     * **URL-адреса**: Определяет конечную точку (endpoint) API, куда направлен запрос.
     * **Заголовков**: Дополнительные данные (например, аутентификация, формат данных).
     * **Тела (Body)**: Дополнительная информация (например, данные для создания ресурса), которая может быть отправлена с запросом.
   * **Ответ (Response)**: Сервер обрабатывает запрос и отправляет клиенту ответ, который может включать данные, статус выполнения и заголовки.
3. **Методы HTTP**
   * **GET**: Получить данные. Например, получить список пользователей.
   * **POST**: Создать новый ресурс. Например, создать новую запись в базе данных.
   * **PUT**: Обновить существующий ресурс. Например, обновить информацию о пользователе.
   * **DELETE**: Удалить ресурс. Например, удалить пользователя из системы.
4. **Эндпоинты (Endpoints)**
   * **Описание**: Эндпоинт — это URL-адрес, к которому клиент обращается через API для выполнения определенного действия. Каждый эндпоинт отвечает за выполнение конкретной функции.
   * **Пример**: В API для управления пользователями может быть несколько эндпоинтов:
     * `/users` — для получения списка пользователей (GET).
     * `/users/{id}` — для получения информации о конкретном пользователе по ID (GET).
     * `/users` — для создания нового пользователя (POST).
     * `/users/{id}` — для обновления данных пользователя (PUT).
     * `/users/{id}` — для удаления пользователя (DELETE).
5. **Параметры запросов**
   * **Query-параметры**: Добавляются к URL для передачи дополнительной информации. Обычно они идут после знака вопроса (`?`) и состоят из ключей и значений.
     * Пример: `/users?age=30&city=London` — запрос на получение списка пользователей старше 30 лет из Лондона.
   * **Path-параметры**: Это часть URL, которая используется для идентификации ресурса.
     * Пример: `/users/{id}` — путь, где `{id}` заменяется на реальный идентификатор пользователя, например, `/users/123`.
6. **Заголовки (Headers)**
   * **Описание**: Заголовки содержат метаданные о запросе или ответе и могут включать такие данные, как формат отправляемой или принимаемой информации, токены аутентификации и многое другое.
   * **Примеры**:
     * `Content-Type: application/json` — указывает, что данные отправляются в формате JSON.
     * `Authorization: Bearer <token>` — используется для передачи токена авторизации.

#### <mark style="color:orange;">Типы API</mark>

1. **REST API (Representational State Transfer)**
   * **Описание**: REST — это архитектурный стиль, который использует HTTP для взаимодействия. RESTful API используют методы HTTP (GET, POST, PUT, DELETE) и стандартизированные URL для обращения к ресурсам.
   * **Принципы REST**:
     * **Статус без сохранения (statelessness)**: Каждый запрос к серверу содержит всю информацию, необходимую для его обработки. Сервер не хранит состояние между запросами.
     * **Клиент-серверная архитектура**: Клиент и сервер разделены, клиент отвечает за пользовательский интерфейс, сервер за данные и логику.
     * **Кеширование**: Ответы API могут кэшироваться для повышения производительности.
     * **Единообразие интерфейса**: Все ресурсы API доступны по предсказуемым и унифицированным путям.
   * **Примеры REST API**:
     * Twitter API, Google Maps API, GitHub API.
2. **SOAP API (Simple Object Access Protocol)**
   * **Описание**: SOAP — это протокол для обмена структурированными сообщениями в формате XML между приложениями по сети.
   * **Принципы SOAP**:
     * SOAP использует XML для форматирования сообщений.
     * Использует более сложные запросы и строгую структуру сообщений.
     * Обычно работает с HTTP, но может также использовать другие транспортные протоколы (например, SMTP).
   * **Применение**: SOAP часто используется в крупных корпоративных системах, где важна высокая безопасность и стандарты передачи данных.
3. **GraphQL**
   * **Описание**: GraphQL — это язык запросов для API, который позволяет клиенту точно указать, какие данные ему нужны. В отличие от REST, клиент может запрашивать только те поля, которые ему необходимы, а не получать все данные по ресурсу.
   * **Преимущества**:
     * Экономия трафика: Клиент получает только нужные ему данные.
     * Гибкость: Возможность объединять запросы к нескольким ресурсам в один запрос.
   * **Пример**: Вместо запроса всех данных о пользователе клиент может запросить только `name` и `email`.
4. **gRPC**
   * **Описание**: gRPC — это фреймворк для удаленного вызова процедур (RPC), который использует протокол HTTP/2 для обмена данными и protobuf (Protocol Buffers) для сериализации.
   * **Преимущества**:
     * Быстрая передача данных благодаря использованию protobuf.
     * Поддержка двунаправленной передачи данных.
     * Хорошо подходит для микросервисной архитектуры.
   * **Применение**: Используется в высоконагруженных системах, микросервисах и системах реального времени.

#### <mark style="color:orange;">Аутентификация и авторизация в API</mark>

1. **Basic Auth**
   * **Описание**: Один из самых простых способов аутентификации, где в заголовке запроса передаются имя пользователя и пароль в закодированном формате (Base64).
   * **Пример заголовка**: `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=`.
2. **OAuth 2.0**
   * **Описание**: Стандартный протокол для авторизации, позволяющий приложениям получать доступ к ресурсам от имени пользователя без передачи его пароля. OAuth использует "токены" для аутентификации и авторизации.
   * **Пример**: Авторизация через социальные сети (например, доступ к информации о пользователе через Facebook или Google).
   * **Основные компоненты OAuth**:
     * **Клиент**: Приложение, запрашивающее доступ к ресурсам.
     * **Ресурсный сервер**: Сервер, который хранит данные (например, Google API).
     * **Авторизационный сервер**: Сервер, который выдает токены авторизации.
     * **Токены доступа (Access tokens)**: Используются для получения доступа к ресурсам.
3. **JWT (JSON Web Token)**
   * **Описание**: Это стандарт для создания токенов доступа, которые содержат полезную нагрузку (payload) в формате JSON, закодированную в виде токена. Эти токены используются для авторизации запросов.
   * **Пример**: Токен, который выдается после успешной аутентификации пользователя и используется для доступа к защищенным ресурсам API.

#### <mark style="color:orange;">Пример работы API</mark>

**Запрос GET**

**Пример запроса**:

```bash
bashCopy codeGET /users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
```

**Ответ**:

```json
jsonCopy code{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}
```

**Запрос POST**

**Пример запроса**:

```bash
bashCopy codePOST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "John Doe",
  "email": "john@example.com"
}
```

**Ответ**:

```json
jsonCopy code{
  "id": 124,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-09-07T10:15:00Z"
}
```

####