Как сделать api запрос

Взаимодействие с API происходит по протоколу HTTPS методом POST.

URL доступа к API:
https://www.testfirm.ru/api/

Обязательными параметрами для каждого запроса являются:
— key — ключ доступа к API (выдается бесплатно при покупке купонов на 300 и более фирм, для его получения заполните форму);
— method — выбранный метод.

Необязательный параметр:
— coupon — код купона.

Если купон указан, то выдаются данные за 2022 год, иначе за 2021.

Примеры выполнения запроса к API (на PHP)

$fields = [‘key’ => ’99c5e07b4d5de9d18c350cdf64c5aa3dd’, ‘method’ => ‘getOrganization’, ‘inn’ => ‘2309085638’]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, ‘https://www.testfirm.ru/api/’); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $results = curl_exec($ch);
$fields = [‘key’ => ’99c5e07b4d5de9d18c350cdf64c5aa3dd’, ‘method’ => ‘getOrganization’, ‘inn’ => ‘2309085638’]; $opts = [ ‘http’ => [ ‘method’ => ‘POST’, ‘header’ => ‘Content-type: application/x-www-form-urlencoded’, ‘content’ => http_build_query($fields) ] ]; $results = file_get_contents(‘https://www.testfirm.ru/api/’, false, stream_context_create($opts));

Результат выполнения запроса к API

Результат всегда возвращается в формате JSON.

В случае неуспешного выполнения запроса возвращаются поля status, error_code, error_text:

В случае успешного выполнения запроса возвращаются поля status и data:

Метод getOrganization

Метод возвращает подробный анализ финансового состояния организации по сравнению с отраслевыми и общероссийскими показателями.

Обязательным параметром для данного метода является inn (ИНН организации).

Описание формата возвращаемых данных (поле data)

Если организация не найдена, возвращается пустой массив.

Ключ Описание

url	Адрес страницы результата анализа на сайте. Если организация не найдена, данный параметр не возвращается.
coefs_year	Год за который расчитаны среднеотраслевые показатели.
org	Массив с основными данными об организации. Если организация не найдена, данный массив не возвращается.
org → inn	ИНН организации.
org → name	Название организации.
org → okved	Код ОКВЭД.
org → okved_text	Название ОКВЭД.
org → revenue	Выручка (в рублях, может отсутствовать).
org → assets	Активы (в рублях, может отсутствовать).
org → org_group	Категория предприятия.
org → org_group_text	Название категории предприятия.
org → region	Код региона.
org → region_text	Название региона.
org → stat_year	Год, за который использовалась отчетность для анализа.
org → last_year	Последний год за который есть отчетность.
tax	Дополнительные данные ФНС, если они были предоставлены.
tax → employees	Среднесписочная численности работников по данным ФНС.
tax → employees → year	За какой год выдаются данные.
tax → employees → data	Количество работников.
tax → tax_system	Используемые специальные налоговые режимы.
tax → taxes	Информация об уплаченных налогах.
tax → taxes → year	За какой год данные.
tax → taxes → taxes_sum	Общая сумма.
tax → taxes → data	Массив уплаченных налогов с соответсвующими суммами.
tax → taxes → data → name	Наименование налога.
tax → taxes → data → value	Сумма в рублях.
tax → tax_penalties	Информация о неуплаченных налогах, штафах, пенях.
tax → tax_penalties → year	За какой год данные.
tax → tax_penalties → tax_penalties_sum	Общая сумма.
tax → tax_penalties → data	Массив неуплаченных налогов, штафов, пеней с соответсвующими суммами, разбитые по типам.
tax → tax_penalties → data → name	Наименование.
tax → tax_penalties → data → items	Список неуплаченных налогов, штафов, пеней.
tax → tax_penalties → data → items → name	Тип: неуплаченный налог, штаф, пеня.
tax → tax_penalties → data → items → value	Сумма в рублях.
result	Массив с результатами анализа фин. состояния организации. Если для анализа не хватило данных отчетности, то данный массив не возвращается.
result → industry	Массив с результатами анализа фин. состояния организации с отраслевыми показателями.
result → industry → okved	Код ОКВЭД, для которого проведен анализ с отраслевыми показателями (может отличаться от ОКВЭД организации, если в базе Росстата и ФНС нет данных).
result → industry → okved_text	Название ОКВЭД.
result → industry → score	Итоговый балл сравнения показателей организации с отраслевыми.
result → industry → score_text	Краткий текст результата сравнения показателей организации с отраслевыми.
result → industry → score_longtext	Полный текст результата сравнения показателей организации с отраслевыми.
result → all	Массив с результатами анализа фин. состояния организации с общероссийскими показателями.
result → all → score	Итоговый балл сравнения показателей организации с общероссийскими.
result → all → score_text	Краткий текст результата сравнения показателей организации с общероссийскими.
result → all → score_longtext	Полный текст результата сравнения показателей организации с общероссийскими.
change	Изменение финансового состояния за год. Если отсутствует отчетность за предыдущий год, то данный массив не возвращается.
change → value	Изменение финансового состояния (в баллах) за год.
change → value_text	Текстовое описание изменения фин. состояния организации за год.
details	Подробности анализа финансового состояния организации. Если для анализа не хватило данных отчетности, то данный массив не возвращается.
details → avtonom	Код показателя.
details → avtonom → title	Название показателя.
details → avtonom → value	Рассчитанное значение данного показателя для организации.
details → avtonom → industry_mediana	Медианное значение данного показателя для отрасли.
details → avtonom → industry_rank	Балл по итогам сравнения показателя организации с отраслевыми.
details → avtonom → all_mediana	Медианное значение данного показателя для РФ.
details → avtonom → all_rank	Балл по итогам сравнения показателя организации с общероссийскими.
warnings	Предупреждения (может отсутствовать).
warnings → fns_no_report	Предупреждение, что организация не сдавала отчетность в ФНС более года.
warnings → fns_debt	Предупреждение, что организация имеет превышающую 1000 рублей задолженность по уплате налогов.
full_report	Сравнительный финансовый анализ показателей в формате HTML.
chart	Данные для построения графика «История финансового состояния»
history	Как менялись выручка (revenue), прибыль (net_profit), активы (assets) и чистые активы (net_assets) фирмы
counter	Количество выполненных запросов за последние 30 дней.

Метод getOrganizationShort

Метод возвращает краткий анализ финансового состояния организации по сравнению с отраслевыми и общероссийскими показателями.

Обязательным параметром для данного метода является inn (ИНН организации).

Описание формата возвращаемых данных (поле data)

Если организация не найдена, возвращается пустой массив.

Ключ Описание

url	Адрес страницы результата анализа на сайте.
name	Название организации.
last_year	Последний год за который у фирмы есть отчетность.
coefs_year	Год за который расчитаны среднеотраслевые показатели.
industry_okved	Код ОКВЭД, для которого проведен анализ с отраслевыми показателями. Если для анализа не хватило данных отчетности, то данный параметр не возвращается.
industry_score	Итоговый балл сравнения показателей организации с отраслевыми. Если для анализа не хватило данных отчетности, то данный параметр не возвращается.
industry_score_text	Полный текст результата сравнения показателей организации с отраслевыми. Если для анализа не хватило данных отчетности, то данный параметр не возвращается.
all_score	Итоговый балл сравнения показателей организации с общероссийскими. Если для анализа не хватило данных отчетности, то данный параметр не возвращается.
all_score_text	Полный текст результата сравнения показателей организации с общероссийскими. Если для анализа не хватило данных отчетности, то данный параметр не возвращается.
counter	Количество выполненных запросов за последние 30 дней.

Метод compareOrganizations

Метод возвращает подробный анализ сравнения финансового состояния двух организаций.

Обязательными параметрами для данного метода являются:
— inn1 (ИНН основной организации);
— inn2 (ИНН организации-конкурента).

Описание формата возвращаемых данных (поле data)

Если организация не найдена, возвращается пустой массив.

Ключ Описание

url	Адрес страницы результата анализа на сайте. Если организация не найдена, данный параметр не возвращается.
coefs_year	Год за который расчитаны среднеотраслевые показатели.
org	Массив с данными об основной организации. Если организация не найдена, данный массив не возвращается.
org → inn	ИНН организации.
org → name	Название организации.
org → okved	Код ОКВЭД.
org → okved_text	Название ОКВЭД.
org → revenue	Выручка (в рублях, может отсутствовать).
org → assets	Активы (в рублях, может отсутствовать).
org → org_group	Категория организации по выручке.
org → org_group_text	Название категории организации по выручке.
org → region	Код региона.
org → region_text	Название региона.
org → stat_year	Год, за который использовалась отчетность для анализа.
competitor	Массив с данными об организации-конкуренте. Если организация не найдена, данный массив не возвращается.
competitor → inn	ИНН организации-конкурента.
competitor → name	Название организации-конкурента.
competitor → okved	Код ОКВЭД организации-конкурента.
competitor → okved_text	Название ОКВЭД организации-конкурента.
competitor → revenue	Выручка (в рублях) организации-конкурента (может отсутствовать).
competitor → assets	Активы (в рублях) организации-конкурента (может отсутствовать).
competitor → org_group	Категория организации-конкурента.
competitor → org_group_text	Название категории организации-конкурента.
competitor → region	Код региона организации-конкурента.
competitor → region_text	Название региона организации-конкурента.
competitor → stat_year	Год, за который использовалась отчетность для анализа.
result	Массив с результатами анализа фин. состояния основной организации. Если для анализа не хватило данных отчетности, то данный массив не возвращается.
result → industry	Массив с результатами анализа фин. состояния основной организации с отраслевыми показателями.
result → industry → okved	Код ОКВЭД, для которого проведен анализ с отраслевыми показателями (может отличаться от ОКВЭД организации, если в базе Росстата и ФНС нет данных).
result → industry → okved_text	Название ОКВЭД.
result → industry → score	Итоговый балл сравнения показателей основной организации с отраслевыми.
result → industry → score_text	Краткий текст результата сравнения показателей основной организации с отраслевыми.
result → industry → score_longtext	Полный текст результата сравнения показателей основной организации с отраслевыми.
result → competitor	Массив с результатами сравнительного анализа фин. состояния организации с показателями конкурента. Если для анализа не хватило данных отчетности о конкуренте, то данный массив не возвращается.
result → competitor → score	Итоговый балл сравнения показателей организации с конкурентом.
result → competitor → score_text	Краткий текст результата сравнения показателей организации с конкурентом.
result → competitor → score_longtext	Полный текст результата сравнения показателей организации с конкурентом.
change	Изменение финансового состояния основной организации за год. Если отсутствует отчетность за предыдущий год, то данный массив не возвращается.
change → value	Изменение финансового состояния основной организации (в баллах) за год.
change → value_text	Текстовое описание изменения фин. состояния основной организации за год.
details	Подробности анализа финансового состояния организации. Если для анализа не хватило данных отчетности, то данный массив не возвращается.
details → avtonom	Код показателя.
details → avtonom → title	Название показателя.
details → avtonom → value	Рассчитанное значение данного показателя для основной организации.
details → avtonom → industry_mediana	Медианное значение данного показателя для отрасли.
details → avtonom → industry_rank	Балл по итогам сравнения показателя основной организации с отраслевыми.
details → avtonom → competitor_value	Рассчитанное значение данного показателя для организации-конкурента (может отсутствовать).
details → avtonom → competitor_rank	Балл по итогам сравнения показателя основной организации с конкурентом (может отсутствовать).
counter	Количество выполненных запросов за последние 30 дней.

Метод calculateInputData

Метод возвращает подробный анализ финансового состояния организации по данным, введенным вручную.

Обязательными параметрами для данного метода являются:
— okved (код вида деятельности (ОКВЭД);
— dimension (размерность исходных данных — 1, 1000, 1000000 (руб.));
— form1 (данные формы №1 «Бухгалтерский баланс»). Параметр указывается в виде массива, где ключами могут быть 1100, 1230, 1240, 1250, 1200, 1300, 1400, 1500, 1600 (1700), а значениями выступают показатели в формате массива, где первый элемент — значение показателя на текущий год, второй элемент — значение показателя за предыдущий год. Все показатели указывать необязательно. В случае отсутствия показателя за предыдущий год можно передавать текущий показатель в виде числа. Подробнее — в примере выполнения запроса.
— form2 (данные формы №2 «Отчет о финансовых результатах»). Параметр указывается в виде массива, где ключами могут быть 2110, 2200, 2400, а значениями выступают показатели в формате числа.

// Вариант 1 $fields = [ ‘key’ => ’99c5e07b4d5de9d18c350cdf64c5aa3dd’, ‘method’ => ‘calculateInputData’, ‘okved’ => ‘62.01’, ‘dimension’ => 1000, ‘form1’ => [ 1100 => [6000, 5000], 1230 => [8000, 9000], 1240 => [0, 0], 1250 => [200, 400], 1200 => [9000, 10000], 1300 => [8000, 9000], 1400 => [6000, 4000], 1500 => [12000, 14000], 1600 => [15000, 16000], ], ‘form2’ => [ 2110 => 10000, 2200 => 500, 2400 => 2000, ], ]; $opts = [ ‘http’ => [ ‘method’ => ‘POST’, ‘header’ => ‘Content-type: application/x-www-form-urlencoded’, ‘content’ => http_build_query($fields) ] ]; $results = file_get_contents(‘https://www.testfirm.ru/api/’, false, stream_context_create($opts)); // Вариант 2 $fields = [ ‘key’ => ’99c5e07b4d5de9d18c350cdf64c5aa3dd’, ‘method’ => ‘calculateInputData’, ‘okved’ => ‘62.01’, ‘dimension’ => 1000, ‘form1’ => [ 1100 => [6000, 5000], 1230 => [8000, 9000], 1250 => 200, 1200 => [9000, 10000], 1300 => 8000, 1400 => [6000, 4000], 1500 => 12000, 1600 => [15000, 16000], ], ‘form2’ => [ 2110 => 10000, 2200 => 500, 2400 => 2000, ], ]; $opts = [ ‘http’ => [ ‘method’ => ‘POST’, ‘header’ => ‘Content-type: application/x-www-form-urlencoded’, ‘content’ => http_build_query($fields) ] ]; $results = file_get_contents(‘https://www.testfirm.ru/api/’, false, stream_context_create($opts));

Описание формата возвращаемых данных (поле data)

Если данных для анализа недостаточно, возвращается пустой массив.

Ключ Описание

result	Массив с результатами анализа фин. состояния организации. Если для анализа не хватило данных отчетности, то данный массив не возвращается.
result → industry	Массив с результатами анализа фин. состояния организации с отраслевыми показателями.
result → industry → okved	Код ОКВЭД, для которого проведен анализ с отраслевыми показателями (может отличаться от ОКВЭД организации, если в базе Росстата и ФНС нет данных).
result → industry → okved_text	Название ОКВЭД.
result → industry → score	Итоговый балл сравнения показателей организации с отраслевыми.
result → industry → score_text	Краткий текст результата сравнения показателей организации с отраслевыми.
result → industry → score_longtext	Полный текст результата сравнения показателей организации с отраслевыми.
result → all	Массив с результатами анализа фин. состояния организации с общероссийскими показателями.
result → all → score	Итоговый балл сравнения показателей организации с общероссийскими.
result → all → score_text	Краткий текст результата сравнения показателей организации с общероссийскими.
result → all → score_longtext	Полный текст результата сравнения показателей организации с общероссийскими.
details	Подробности анализа финансового состояния организации. Если для анализа не хватило данных отчетности, то данный массив не возвращается.
details → avtonom	Код показателя.
details → avtonom → title	Название показателя.
details → avtonom → value	Рассчитанное значение данного показателя для организации.
details → avtonom → industry_mediana	Медианное значение данного показателя для отрасли.
details → avtonom → industry_rank	Балл по итогам сравнения показателя организации с отраслевыми.
details → avtonom → all_mediana	Медианное значение данного показателя для РФ.
details → avtonom → all_rank	Балл по итогам сравнения показателя организации с общероссийскими.
counter	Количество выполненных запросов за последние 30 дней.

Метод checkOrganization

Метод проверяет содержится ли фирма с указанынм ИНН в базе, а так же можно ли получить по ней анализ финансового состояния.

Обязательным параметром для данного метода является inn (ИНН организации).

Описание формата возвращаемых данных (поле data)

Ключ Описание

inn	ИНН организации.
name	Название организации.
last_year	Последний год за который есть отчетность.
coefs_year	Год за который расчитаны среднеотраслевые показатели.
report	Boolean переменная — если равна true, то можно получить анализ финансового состояния, а если false, то либо фирма не занимается коммерческой деятельностью, либо бухгалтерских данных не достаточно для составления анализа.

Источник: www.testfirm.ru

Выполнение запросов#

Адрес запроса формируется из номера аккаунта idInstance и ключа доступа apiTokenInstance , которые требуется предварительно получить в Личном кабинете согласно разделу Перед началом работы.

В качестве параметра method используется требуемый метод API, описанный в Документации API.

Пример запроса для отправки сообщения методом SendMessage:

https://api.green-api.com/waInstance1234/SendMessage/bde035edae3fc00bc116bd112297908d8145e5ba8decc5d884

Заголовки запроса#

Большинство запросов должны содержать стандартные заголовки:

• Content-Type — application/json

В некоторых случаях заголовки могут отличаться, например, для метода отправки файла SendFileByUpload

Отладка запросов#

Для отладки запросов к Green API рекомендуется использовать Коллекцию Postman

Источник: green-api.com

Простое объяснение Web API на примере продажи фермерских продуктов

Перевод статьи «Web APIs explained by selling goods from your farm».

Если вам случалось бывать на продуктовом рынке или на ярмарке, вы вполне сможете понять концепцию API (англ. application programming interface, варианты перевода — прикладной интерфейс приложения или программный интерфейс приложения).

Даже начинающим программистам, скорее всего, неоднократно встречалась аббревиатура «API».

• «Не могу дождаться, когда уже эта компания выпустит свой публичный API!»
• «API этой компании это какой-то бардак!»
• «Есть у них в API endpoint для этих данных?»

Понять концепцию прикладного интерфейса приложения (API) может быть довольно сложно, если вы не знакомы с такими концепциями как SOAP, HTTP и XML.

Я решил найти способ объяснить работу web API в целом. Таким образом, когда вы углубитесь в технические детали, у вас уже будет понимание того, как это работает все вместе.

В этом руководстве вы будете собственником фермы, который продает пять видов продуктов: курятину, свинину, яйца, помидоры и кукурузу.

Чтобы разобраться в этой статье, вам нужно понимать разницу между бэкендом и фронтендом приложений. Если вы с этой темой пока не знакомы, можно для начала почитать мою статью о GET/POST.

Разница между GUI и API

Давайте начнем со знакомого способа использования веба. Браузер, скажем, Chrome, это пример графического пользовательского интерфейса (GUI). Вы как пользователь можете взаимодействовать с дружественным к вам инструментом для решения ваших задач. Например, при помощи браузера вы можете заказывать билеты на самолет или искать что-то в Google.

Графический пользовательский интерфейс (GUI) позволяет посетителям сайта взаимодействовать с кодом на сервере контролируемым и структурированным образом.

Если провести аналогию с фермой, то GUI будет прилавком на рынке или стендом на ярмарке.

Если вы будете просто держать свои товары на складе, позволяя пользователям заходить туда, много вы не заработаете. Вместо этого нужно поставить киоск или палатку и разложить там товар, чтобы покупатели могли быстро понять, чем вы торгуете и сколько это стоит.

Таким образом покупатели «взаимодействуют» с плодами вашего тяжелого труда. Им не нужно разбираться в процессе выращивания овощей, не нужно знать, какими инструментами вы при этом пользуетесь. Они просто видят конечный продукт.

Обратите внимание, что опыт каждого отдельного покупателя это личное взаимодействие, один на один. Если покупатель пришел в вашу палатку, н хочет купить товары именно с вашей фермы.

Что такое API?

Помимо прямых продаж потребителям есть и другие способы продавать продукты. Вы можете продавать свои товары дистрибьюторам и местным ресторанам, а они используют их в различных блюдах или продадут в продуктовые магазины.

Для потребителя это новый способ «употребить» ваш продукт. Он может и не знать, чьи яйца использовались для приготовления омлета, заказанного им на завтрак в ресторане, но он все равно «потребляет» ваш продукт.

Но с точки зрения собственника фермы это совершенно другая процедура продаж. Теперь вам не нужно заботливо оформлять свою палатку и раскладывать товары для покупателей. Вместо этого вам, вероятно, понадобится подъезд к складу, чтобы дистрибьюторы и рестораторы могли подъезжать грузовиками и загружаться. Также вам нужно упаковать ваши товары для оптовых продаж.

Вот это уже близко к концепции API. Создавая API, вы даете возможность другим разработчикам иметь доступ к вашим данным и использовать их в своих приложениях.

Как клиенты ресторана могут употребить яйца ваших кур, заказав омлет, так и пользователи сайтов могут «потребить» ваш продукт на чьем-то еще сайте при помощи виджета или кода на серверах другой компании.

Теперь у нас есть новый уровень взаимодействия. Ваши дистрибьюторы и рестораторы могут взаимодействовать с вами лично, посещая ферму, но затем они предлагают ваши продукты тысячам покупателей.

Вам как собственнику фермы все равно нужно налаживать процессы продаж, чтобы успешно обслуживать дистрибьюторов. Аналогично, API это структурированный способ использования вашего бэкенд-кода другими людьми. У вас как разработчика по-прежнему сохраняется полный контроль.

На иллюстрации в качестве примера я использовал виджет поиска, но на самом деле для доступа к API может использоваться что угодно. Это лишь распространенный пример использования на сайтах сторонних API. Но есть и другие примеры:

• карты;
• обработка платежей;
• виджеты погоды.

К чему можно получить доступ при помощи API?

Скажем, вы хотите начать продавать дистрибьюторам и рестораторам яйца со своей фермы. Для этого вам нужно будет наладить кое-какие процессы. Вам понадобится:

1. Хранить яйца в больших количествах.
2. Вести бухгалтерию, чтобы ежемесячно выставлять счета клиентам.
3. Обустроить площадку для погрузки яиц в грузовики.

Прежде чем начать всем этим заниматься, вы должны понять, готовы ли вы вообще принимать оптовые заказы на яйца. Есть ли у вас достаточно кур, чтобы еженедельно производить нужное количество яиц? Если ваша система попросту не готова к массовому производству, яйца у вас быстро кончатся, а клиенты разочаруются.

Разработчики API создают endpoints (конечные точки), позволяющие другим разработчикам получать доступ к конкретным данным в базе данных. В приведенном выше примере это был бы endpoint «яйца». Если вы не создадите endpoint, ваши клиенты просто не смогут купить у вас яйца.

Вы можете установить отдельные endpoints для каждого вида продуктов вашей фермы: для курятины, яиц, свинины, помидоров и кукурузы. Некоторые продукты могут быть доступны только на рынке (GUI), потому что вы не уверены, что потянете производство этих продуктов для оптовых продаж.

В этом заключается разница между API и базой данных с открытым исходным кодом. В такой базе данных можно создать любой запрос и получить доступ к любым данным. Когда вы создаете API для вашего бэкенда, вы создаете endpoints, которые открывают только определенные данные.

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

Рассматриваем отдельный вызов API

Допустим, вы решили создать endpoint для яиц на вашей ферме. Местный ресторан хочет покупать по 1000 яиц, чтобы иметь возможность готовить омлеты, которые еженедельно заказывают 1000 раз.

Обратите внимание, что вызов API начинается с запроса пользователя. Если смотреть на описание, это может не быть очевидным.

Отдельный вызов API происходит, когда срабатывает какой-то триггер в результате чего другой разработчик отсылает запрос к вашему API на определенный endpoint. Ваш API должен доставить ответ, основанный на вашем бэкенд-коде.

В аналогии с фермой триггером является заказ 1000 яиц. Менеджер ресторана уже договорился с вашей фермой о поставках. А ваша ферма уже создала все условия для отправки 1000 яиц за раз.

Таким образом, когда поступает заказ на 1000 яиц, ваша ферма доставляет ответ: 1000 яиц.

Имейте в виду, что договориться с вашей фермой о поставках могли 100 разных ресторанов, и 10 из них могут прислать заказы одновременно! Здесь в игру вступает масштабируемость. Вы должны определиться, готов ли ваш сервер удовлетворить такой спрос. Но это тема для другой статьи.

Вот техническая версия описанной выше последовательности. Здесь у вас есть картографическое приложение, которое может использоваться на сайтах (как Google Maps).

1. Какой-то пользователь на каком-то чужом сайте использует ваше картографическое приложение и осуществляет действие, для которого требуются данные с вашего сервера.
2. Разработчик этого сайта уже написал код, который создаст запрос к вашему API, основываясь на действиях пользователя.
3. Происходит вызов API, и ваш сервер доставляет ответ.

Конечно, ваш картографический виджет может использоваться на 1000 других веб-приложений, так что нужно быть готовым обслуживать все эти вызовы API!

Примеры GET и POST

Пока что в наших примерах с фермой были сценарии, напоминающие запросы GET. Когда посетители ресторана делают заказы, ресторан посылает грузовик на вашу ферму, чтобы забрать яйца.

Но как насчет запросов POST? Если обратиться к примерам из жизни, API Facebook позволяет пользователям других приложений создавать посты, а затем эти приложения могут отправлять созданные посты прямо на Facebook для моментальной публикации.

В некоторых случаях, как с API соцсетей, может иметь смысл позволить конечным пользователям постить что-либо в социальной сети прямо из стороннего приложения.

Но есть и другой пример. API Amazon позволяет собственникам онлайн-магазинов публиковать информацию об их товарах на торговой площадке Amazon. В такой ситуации разработчик независимого онлайн-магазина также может реализовать присутствие этого магазина на Amazon. В этом случае API никак не будет связан с конечными пользователями или посетителями сайта.

В нашем примере с фермой это похоже на обработку ежемесячных счетов. После того как дистрибьюторы и рестораторы весь месяц посещали вашу ферму и покупали продукты, вы в конце месяца выставляете им счет, где расписываются все нужные платежи.

Ресторан должен не только вовремя забирать нужные ему яйца и разработать для этого особую процедуру. Он также должен обеспечить своевременную оплату по вашему счету. Здесь, вероятно, будет участвовать их бухгалтер. Скажем, бухгалтер знает, что ресторан должен платить вам первого числа каждого месяца.

Как пользователь (покупатель) может запустить триггер для запроса POST? Представим, что ресторан немедленно отправляет вам платеж каждый раз, как кто-то заказывает продукты с вашей фермы. Если человек заказал омлет за 5 долларов, 2 доллара причитаются вашей ферме за яйца, и ресторан немедленно переводит их на ваш банковский счет. Если бы это было веб-приложение, такой уровень коммуникации мог бы сработать, но поскольку это ферма, подобный порядок был бы слишком непрактичным.

Разница между фермой и веб-приложением

Как видно из предыдущего примера, между цепочкой поставок на ферме и вызовом API есть существенная разница. Тайминг.

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

Давайте рассмотрим пример запроса GET, который мы уже разбирали ранее.

Применительно к веб-разработке здесь происходит следующее:

1. Пользователь осуществляет какое-то действие, запускающее запрос.
2. Код бэкенда направляет вызов API к endpoint.
3. API доставляет нужную информацию.

Но если проводить аналогию с фермой,

1. Пользователь заказывает омлет.
2. Ресторан посылает грузовик забрать яйца с вашей фермы.
3. Яйца доставляются в ресторан и из них готовится омлет.

Было бы невероятно непрактично посылать грузовик на ферму за каждой парой яиц (хотя это был бы самый свежий омлет в истории человечества). Но шаги те же самые. Я просто хотел бы подчеркнуть разницу в тайминге.

А вот когда пользователь веб-приложения производит какое-то действие, запускающее отправку запроса, обычно он получает ответ немедленно.

Что означает «открыть API»?

Вернемся к одному из вопросов начала статьи. Что происходит, когда компания «открывает свой API»?

Это значит, что на сервере этой компании есть какие-то ценные данные, к которым теперь можно получить доступ через определенные endpoints. Компании нужно определить, каким образом разработчики из других компаний могут получать их данные, но в то же время они делают эти данные (в структурированном виде) доступными широкой общественности.

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

Источник: techrocks.ru