Что такое API и как он работает

В этом руководстве содержится все, что вам нужно знать об API, чтобы начать использовать «API-модули» в MenuBuilderBot.

API - (Application Programming Interface) - это способ для двух отдельных компьютеров общаться друг с другом. Мобильные или Веб-приложения могут общаться с Серверами. API - помогает вам ПОЛУЧАТЬ ДОСТУП К ДАННЫМ внешних проектов и сервисов, РАСШИРЯТЬ ФУНКЦИОНАЛЬНОСТЬ вашего собственного проекта, ИЗБЕГАТЬ СЛОЖНОСТИ в разработке.

Мы объясним API на примере REST-API. REST-API - это НЕ протокол, это НАБОР ПРАВИЛ, которым разработчики соглашаются следовать при создании API для своих проектов.

ПРЕДУПРЕЖДЕНИЕ: Это НЕ полное руководство по REST-API или вообще по API - данное руководство ограничено только информацией, которую вам необходимо знать для начала.

❖ Основы API

Основные положения API

1. API обеспечивает цикл клиент-серверных запросов и ответов. Все запросы и ответы проходят через протокол HTTP.
2. У каждого сервера есть ресурсы для вызова. Каждый ресурс имеет уникальный URI (унифицированный идентификатор ресурса). URI идентифицируют конкретный ресурс на сервере.
3. Версия API является частью URI.
4. Клиент (ваше приложение) взаимодействует с ресурсом, отправляя запрос к конечной точке (Endpoint) этого ресурса по HTTP.
5. URI запрос имеет HTTP VERB, например GET (прочитать существующий ресурс) или POST (создать новый ресурс).
6. Каждый ответ содержит HTTP STATUS CODE, чтобы сообщить клиенту (вашему приложению), что произошло с запросом (список кодов статуса — см. ниже).
7. Каждый запрос и ответ (цикл) независимы от всех остальных.

Коды статуса HTTP

Это далеко не полный список кодов — лишь несколько примеров, чтобы вы получили общее представление.

1xx Информационный

100 Продолжить: Начальная часть запроса получена|
101 Переключение протокола: Сервер переключает протоколы

2xx Успешно

200 ОК: Успех
201 Создано: Ресурс создан

3xx Перенаправление

308 Постоянное перенаправление: Ресурс был перемещён навсегда.

4xx Ошибка клиента

400 Bad Request: Неправильный синтаксис запроса
401 Unauthorized: Требуется аутентификация

5xx Ошибка сервера

500 Внутренняя ошибка сервера: Ошибка сервера
502 Неверный шлюз: Неверный ответ от вышестоящего сервера

API-запрос

Это вызов (запрос) от Клиента (вашего приложения или бота) к Серверу проекта или сервиса, от которого вы пытаетесь получить информацию.

Структура запроса HTTP GET (общая):

URI = Базовая ссылка + Конечные точки (Ресурсы) + Параметры

Базовая ссылка:
http://domain.name/api/
Базовая ссылка содержит - адрес API на веб-сайте

Базовая ссылка + Конечная точка (Endpoint):
http://domain.name/api/v1/users
http://domain.name/api/v1/products
Конечная точка (Endpoint) содержит - версию и ресурс, к которому вы обращаетесь

Базовая ссылка + Конечная точка + Параметры:
http://domain.name/api/v1/users?user=id&data=address
http://domain.name/api/v1/products?product=id&data=amount
Параметры, содержащие - информацию о конкретных данных, которые вы запрашиваете у Ресурса.

Ответ API

Это ответ (Response) от Сервера проекта или сервиса на ваш Запрос.

Ответы API могут различаться в зависимости от характера запроса или информации, которую необходимо вернуть.

Тело ответа может содержать такие элементы, как:
- запрошенные данные
- подтверждение того, что ресурс был создан или обновлён
- сообщение об ошибке
- изображения
- текст (обычными форматами текста, возвращаемого в теле ответа, являются JSON, XML, HTML, YAML и простой текст).

Большинство ответов вы получите в формате JSON, поэтому давайте познакомимся с его основами.

❖ Формат JSON

JSON (JavaScript Object Notation) - это открытый стандартный, читаемый человеком текстовый формат обмена данными для хранения, передачи и представления структурированных объектов данных, состоящих из пар Имя:Значение, объектов и массивов.

Несмотря на то, что изначально этот формат хранения был создан для JavaScript, он оказался настолько удобным, что сегодня его используют и в других системах - в частности, для передачи данных через API, независимо от того, на каком языке программирования был создан сам проект.

Структура файла JSON (синтаксис)

В самом общем виде JSON представляет собой формат «Ключ:Значение», разделённые запятыми.

Ключ должен иметь тип «String», а Значение может иметь любой из следующих типов:
- Число
- Строка
- Логическое значение
- Массив
- Объект
- null

Цель данного руководства - научить вас не ПИСАТЬ корректные файлы JSON, а ЧИТАТЬ их. Это позволит вам правильно определять имеющиеся СУЩНОСТИ, что, в свою очередь, облегчит вам обращение к данным, которые вы получаете от API.

По сути, файл JSON состоит из двух сущностей - ОБЪЕКТОВ и МАССИВОВ, - смешанных в различных комбинациях.

Все, что вам нужно для работы с его данными, - это иметь возможность чётко идентифицировать эти ДВЕ СУЩНОСТИ (независимо от того, как они выглядят в конкретном файле), чтобы вы могли использовать ПРАВИЛЬНЫЙ СИНТАКСИС для получения данных изнутри этих сущностей.

ОБЪЕКТ
ОБЪЕКТ - это НЕУПОРЯДОЧЕННЫЙ набор пар Ключ:Значение, заключённых в фигурные скобки "{...}".
Порядок расположения пар Ключ:Значение не принципиален.
Объекты могут содержать несколько Свойств (Properties) Ключ:Значение, другие Объекты и Массивы.
Каждое свойство Объекта имеет своё собственное ИМЯ (Ключ) и ссылается на это Имя.
Объекты используются для хранения любых разрозненных данных.

МАССИВ
МАССИВ - это УПОРЯДОЧЕННЫЙ набор значений, заключённый в квадратные скобки «[...]».
Порядок значений важен.
Массивы содержат список похожих элементов, других Объектов и Массивов.
Каждое Свойство (Property) Массива имеет свой собственный НОМЕР ИНДЕКСА (как ключ) и ссылается на него по этому номеру.
Нумерация элементов Массива происходит с [0] (нуля). То есть ПЕРВЫЙ элемент массива имеет индекс - [0] - ноль.
Массивы используются для хранения скорее однородных данных.

Давайте рассмотрим основные СУЩНОСТИ и атрибуты (свойства, представленные ключами и значениями), которые присутствуют в структуре следующего примера JSON:

{
"firstName": "John",
"lastName": "Connor",
"dob": "28-02-1985",
"age": 15,
"married": false,
"driverLicence" null,
"address": {
    "street": "Valerio Street",
    "city": "Winnetka",
},
"hobbies" ["games", "bike", "hack"],
"friends": [
    {
    "firstName": "Bob",
    "age": 30,
    },
    {
    "firstName": "Tim",
    "age": 14,
    }
]
}

У JSON из примера выше есть несколько Атрибутов:
1. «firstName», «lastName» и другие - это список (так называемый «словарь») простых Свойств (Properties).
2. «address» - это ещё один «вложенный» Объект, содержащий свои собственные Свойства.
3. «hobbies» - это простой Массив.
4. «friends» - это Массив, содержащий Объекты со своими собственными Свойствами.

Всякий раз, когда вы запрашиваете какие-либо данные из внешнего API, вы получаете похожую структуру JSON.

Информацию о том, как ссылаться на Свойства каждой конкретной сущности (Объекта или Массива), см. в следующем руководстве «Работа с API Модулями».