Внешний API запрос

Не слишком много теории?

Давайте отработаем это на практике. Откроем уже AppMaster, создадим API запрос с его помощью и получше разберемся с тем, как этот запрос устроен.

Создание внешнего API запроса

API запросы создаются в разделе “Business logic”, во вкладке “External API Requests”.

Пришло время нажать “+ New API Request”

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

Давайте разбираться с данными, которые действительно имеют значение.

Необходимым минимумом для создания запроса является указание его метода (Method) и адреса (URL). Начнем с последнего.

URL

URL - Uniform Resource Locator (Унифицированный Указатель Ресурса). Адрес, который выдан конкретному ресурсу в Интернете. Самым привычным вариантом такого ресурса является HTML-страница - мы вводим ее URL в адресной строке браузера и открываем нужный сайт. При этом сам ресурс может быть любым, картинка, видео, набор данных. Главное, что у этого ресурса есть конкретный указатель - URL, на который можно послать запрос для получения данного ресурса.

Методы

Обращаясь к данным по их адресу указываем еще и метод (еще можно сказать тип) запроса, то есть сообщаем, что собственно нужно сделать с этими данными.

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

Разберемся с тем, какие еще методы существуют.

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

GET. С ним уже разобрались. Метод запрашивает предоставление ресурса, получает данные.

POST. Чтобы взять данные откуда-то, сначала нужно эти данные там разместить. Метод POST делает именно это. Отправляет данные на сервер, создает ресурс

PUT. Похож на метод POST, но его задача заключается в обновлении данных. Он не создает новые данные, но заменяет уже существующие, обновляет их.

DELETE. Как и следует из названия - удаляет данные.

PATCH. Метод похож на PUT, но используется для частичного обновления данных, а не замены их целиком. Например, методом PATCH можно поменять заголовок статьи, или изменить значение какого-либо параметра.

Важно учитывать тот факт, что сервер вообще не обязан делать именно то, что указано в методе. Мы можем отправить адрес какой-то страницы с методом DELETE, но это не означает, что сервер действительно её удалит. Зато, чисто теоретически, он может сделать это по команде GET. Или ничего не изменять у себя, но при этом отправить данные в ответ на POST. Просто потому, что разработчик настроил его именно так.

Вот тут в игру и вступает REST, который говорит, что пора договориться о соблюдении порядка, прекратить бардак и делать именно то, что указано в методе. По крайней мере это должно быть основной задачей (хоть и не обязательно единственной). Как пример - при передаче содержимого статьи методом GET можно заодно и увеличить счетчик количества ее просмотров на 1.

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

URL Params

URL Params. Бывают ситуации, когда мы знаем только часть адреса URL. В качестве примера можно привести статьи на сайте Appmaster.io. Начальный адрес у всех статей одинаковый - https://appmaster.io/blog/. Но дальше у каждой статьи свое название и, соответственно, своя индивидуальная часть для точного указания именно на эту статью.

В подобной ситуации используются URL Params. Общую часть прописываем сразу, а с остальным оставляем возможность определиться в процессе. По итогу URL записывается в виде https://appmaster.io/blog/:id/

Известная часть записывается как есть, а переменная после знака “:”. Название этой переменной части (уже без “:”) и добавляется в список параметров. При этом переменных частей может быть несколько, а их расположение в любом месте URL.

Query Params

Query Params. Помните, как в первом модуле мы отправляли запрос на boredapi.com? И помимо адреса прописывали дополнительные данные. Вот это и были Query Params (параметры запроса).

Они записываются после URL  и отделяются от него знаком “?”. Указывается наименование параметра, знак “=” и само значение параметра. В случае использования сразу нескольких параметров они разделяются знаком “&”.

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

Query Params используются, когда источник данных один, но сами данные при этом могут быть разные. Например, Boredapi содержал в себе огромный список дел, которыми можно заняться. Но нас интересовали только те, которые предназначены для одного человека и именно это мы указали в параметрах запроса.

Другой вариант использования - ограничение количества данных. Например, мы могли бы обращаться к какому-то списку, но запрашивать из него только первые 5 записей. Это количество тоже может быть параметром запроса.

Еще один вариант - ключ для доступа. Вы могли использовать этот параметр в задании модуля 1 при обращении к Alphavantage. Данные можно было получить только после регистрации и отправки персонального ключа в параметрах запроса.

Обратите внимание на страницы, которые вы посещаете в Интернете, наверняка в них тоже обнаружите различные параметры. Например, откройте страницу погоды в Яндексе, в параметрах запроса там отправляются географические значения широты и долготы.

Headers

Headers. Заголовки запроса. Обычно в заголовках содержится служебная информация о запросе (мета-информация). Заголовки позволяют серверу получить больше информации о клиенте, который запрашивает данные. В заголовках может быть информация о том, какой браузер используется, в какой кодировке ожидается ответ, на каком языке, точное время запроса и многое другое. В случае доступа к защищенным данным в заголовках может указываться ключ авторизации.

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

Body

Body. Тело запроса. GET-запросы обычно обходятся без него, но если мы хотим передать какие-то данные серверу, отправить POST или PUT-запрос, то эти данные размещаются именно в теле запроса. При этом в теле запроса можно разместить данные любой сложности, например, отправить видеофайл, а не ограничиваться какой-то цифрой или текстовой строкой.