API сервисы


Содержание

API Сервиса Словесных Ассоциаций

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

Возможности REST API для поиска ассоциаций:

  • Все запросы передаются по защищённому HTTPS соединению.
  • Результат выполнения запроса может быть представлен формате данных JSON или XML.
  • Поиск ассоциаций для заданного слова.
  • Возможность поиска не только по одному слову, но и по словосочетанию.
  • Поиск словесных ассоциаций для следующих языков: русский, английский, французский, испанский, немецкий, итальянский, португальский.
  • Поиск ассоциаций в одном из двух следующих направлений* :
    • а) Входными данными является слово-стимул. Сервис возвращает список ассоциативных слов-ответов, которые приходят на ум для заданного слова-стимула.
    • б) Входными данными является слово-ответ. Сервис возвращает список слов-стимулов, которые чаще всего побуждают подумать о заданном слове-ответе.

    * Если задача состоит в том, чтобы узнать каие слова возбуждает выбранное слово-стимул, то следует использовать вариант а). Если требуется подобрать слова, которые натолкнут на мысль или побудят человека подумать о выбранном слове-ответе, то следует использовать вариант б).

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

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

REST API доступен на коммерческой основе с ежемесячной подпиской на следующие тарифные планы:

Тарифный план Количество запросов за календарный месяц Стоимость подписки в месяц (для выбранной валюты)
RUB USD EUR GBP
Start До 5,000 Бесплатно Бесплатно Бесплатно Бесплатно
Basic До 50,000 600 10 9 8
Standard До 200,000 1800 30 27 24
Premium До 500,000 4200 70 63 56
Enterprise До 5,000,000 36000 600 540 480

Вопросы и ответы

Защищены ли данные моей кредитной карты?
Оплата осуществляется через PayPal, электронную платёжную систему, которая соответствует стандарту безопасности данных PCI DSS. Наш веб сайт не имеет доступа к какой-либо информации о банковской карте.

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

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

Можно ли резидентам Российской Федерации использовать для оплаты валюту, отличную от рубля?
Нет, в России производить оплату можно только в рублях. В соответствии с законодательством Российской Федерации совершение валютных операций между резидентами Российской Федерации запрещены.

Возможно ли изменить валюту аккаунта и часовой пояс?
При создании аккаунта вам нужно будет выбрать валюту и часовой пояс. Однако, вы не сможете изменить валюту и часовой пояс впоследствии, поэтому отнеситесь внимательно к этому выбору. Эти параметры являются ключевыми при выставлении счетов. Если вы хотите использовать другую валюту, создайте новый аккаунт API Сервиса Словесных Ассоциаций и выберите нужный вариант в процессе регистрации.

Где можно найти формальную спецификацию Swagger для API Сервиса Словесных Ассоциаций?
Swagger спецификацию в JSON формате можно скачать здесь: https://api.wordassociations.net/documentation/swagger.json, а в YAML формате здесь: https://api.wordassociations.net/documentation/swagger.yaml. В интернете есть множество сервисов, которые по Swagger спецификации могут сгенерировать код API клиента практически на любом популярном языке программирования.

По-прежнему есть вопросы?
Свяжитесь с нами по e-mail.

Что такое API и как интегрировать свой сайт с SendPulse

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

Рекомендуем показать эту статью разработчику, который будет настраивать передачу данных. В ней мы расскажем как использовать API email сервиса SendPulse, а также на примере покажем, как создать новостную рассылку и получить по ней статистику.

Что такое API

API расшифровывается как Application Programming Interface, что в переводе означает «интерфейс программирования приложений». API — это интерфейс, в котором приложения взаимодействуют между собой, выполняя общую задачу.

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

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

Чем API может помочь маркетологу

Маркетологам приходится проявлять гибкость в получении данных. Они собирают информацию из разных каналов, а те часто не предлагают привычный интерфейс. При передаче информации через API из одной системы в другую не важны интерфейсы этих систем. Главное, что обе стороны признают общие параметры запросов и ответов. Так информация передается быстро. И это важно для задач, требующих точности и оперативности.

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

Что можно сделать с помощью API в SendPulse

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

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

Как использовать сервис SendPulse c применением API

Для тестирования и иллюстраций API в этой статье мы использовали Postman, инструмент для тестирования API. Данная программа доступна для пользователей Mac, Windows и Linux и не требует изучения языков программирования. Программа работает в режимах запуска, тестирования, документации и отслеживания. Вы можете пользоваться любым похожим приложением.

Сейчас мы рассмотрим пример того, как создать новостную рассылку и получить по ней статистику через API.

1. Авторизируемся в сервисе

Для этого получаем токен-ключ авторизации, используя метод из документации SendPulse. Возьмите значения API ID и API Secret из настроек вашего аккаунта SendPulse.

Значения API ID и API Secret из настроек аккаунта в SendPulse

Отправьте по API запрос на получение токена с этими значениями. В ответе сервиса будет предоставлен access token и указан его тип.

Ответ сервиса SendPulse с указанием access token и его типа

Этот токен понадобится для подписи каждого запроса по API. Учтите: после генерации токен действует час, потом придется обновить его — повторить первый шаг. Также в настройках аккаунта обновляйте значения API ID и Secret в целях безопасности. После этого тоже нужно сгенерировать новый токен.

2. Создаем адресную книгу

3. Получаем ID адресной книги


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

Значения ID адресных книг в ответе API email сервиса SendPulse

4. Загружаем адреса в адресную книгу

При добавлении адресов в адресную книгу передаются и переменные — в данном случае это переменная <> со значением <>.

Добавление через API email адресов в адресную книгу

5. Загружаем шаблон письма

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

Загрузка шаблона письма по API email сервиса SendPulse

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

ID загруженного шаблона в ответе API email сервиса SendPulse

Если готового шаблона у вас нет, создайте его в блочном редакторе SendPulse.

6. Создаем рассылку по адресной книге

Вместо параметра «body» подставьте параметр «template_id» со значением из предыдущего шага.

Передача значения параметра «template_id» по API сервиса SendPulse

7. Получаем информацию об отправленной кампании

Для маркетолога важно знать данные о статусе кампании. По API email сервиса SendPulse можно получить информацию по рассылке. На иллюстрации ниже мы видим данные о кампании: имя и адрес отправителя, тему и содержимое письма, количество писем в рассылке, статус и дату отправки.

Информация об отправленной кампании, полученная по API email сервиса SendPulse

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

Подробную аналитику по вашим email рассылкам удобно просматривать непосредственно в аккаунте SendPulse.

8. Смотрим как письмо выглядит в ящике получателя

Как видно на примере ниже, в хедере письма отображается имя подписчика, которое мы передали с помощью переменной <>, когда добавляли адреса получателей в адресную книгу.

Значение переменной передалось при добавлении контакта в адресную книгу по API email сервиса SendPulse

9. Если нужно отправить авторассылку

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

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

Цепочка авторассылки в Automation 360 от SendPulse

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

Что в итоге

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

API сервисы

API (application programming interface) — это набор готовых классов, функций, процедур, структур и констант. Вся эта информация предоставляется самим приложением (или операционной системой). При этом пользователю не обязательно понимать, что это API технология обеспечивает взаимодействие модулей. Цель предоставленной информации – использование этих данных при взаимодействии с внешними программами.

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

В общем случае данный механизм применяется с целью объединения работы различных приложений в единую систему. Это достаточно удобно для исполнителей. Ведь в таком случае к другому приложению можно обращаться как к «черному ящику». При этом не имеет значения его внутренний механизм – программист может вообще не знать, что такое API.

Функции API

В процессе работы элементы механизма API организуют многоуровневую иерархию. При этом подчиненные компоненты также получают подобную структуру. Внутри стандартной сетевой модели OSI выделяют как минимум 7 внутренних уровней. Они классифицируются от физического уровня трансляции бит до приложений, таких как протоколы HTTP и IMAP. Таким образом API верхнего использует функциональность нижнего.

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

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

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

Эти компоненты дают возможность компилятору опознать функцию в языке C++. В тех случаях, когда она является методом определенного класса, ее сигнатура включается в имя этого класса.

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

Типы API

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

В отдельные группы выделяют интерфейсы управления графическими компонентами программных модулей (API графических интерфейсов wxWidgets, Qt, GTK и т. п.), операционными системами (Amiga ROM Kernel, Cocoa, Linux Kernel APIruen, OS/2 API, POSIX, Windows API), звуковые (DirectMusic/DirectSound, OpenAL), оконные интерфейсы и так далее. Здесь их разделение определяется уровнем приложения в иерархии и функциональностью. Пользователи компьютерных игр обычно не подозревают, что это графический API обеспечивает им такую быструю отрисовку картинки и поразительную яркость изображений.

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


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

  1. Трудности портирования кода программы при переходе от одной API к другой. Они часто появляются при переносе модулей в другие операционные системы.
  2. Снижения объема функциональности интерфейса при переходе к управлению с более низкого уровня на высокий. В этом случае облегчается выполнение строго определенного класса задач. При этом возможности доступа к элементам управления другими регуляторами теряются. Ведь более низкий уровень позволяет легко управлять базовыми компонентами программы.

API вебмастеров / поисковых систем

Для вебмастеров и программистов особенно важны Web API. Такие системы управления включают в себя комплект HTTP-запросов. В результате получения таких запросов модуль генерирует строго определенную структуру HTTP-ответов. Для транспортировки информации между ними принято использовать форматы XML или JSON.

Фактически в этом случае название Web API будет синонимом обозначения веб-службы. Иными словами, это определенные программные системы со своими интерфейсами. Для получения конкретного доступа к ним используется идентификация в сети по веб-адресу. Например, при передаче данный на сервер применяется серверный API.

В случае построения программных систем на основе сервис-ориентированной архитектуры именно веб-служба является уровнем формирования модулей.

Для обычных пользователей такие службы являются синонимами абсолютно обычных решений в Интернете. Это может быть почта, поисковая система, сервис хранения файлов, социальных закладок и так далее. В случае необходимости тестирования веб-службы на больших объемах разнообразных данных соответствующий API testing предоставляет механизм для такой объемной работы.

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

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

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

При этом нужно учитывать изменения в интерфейсах, произошедшие после массового внедрения стандартов Web 2.0. В результате был выполнен переход протокола обмена структурированными данными в распределенной вычислительной среде SOAP (от англ. Simple Object Access Protocol — простой протокол доступа к объектам) к архитектурному стилю взаимодействия компонентов распределенного приложения в сети REST (сокр. от англ. Representational State Transfer — «передача состояния представления»). Для многих веб-служб, в число которых входят поисковые системы и интернет-магазины, данный переход привел к упрощению архитектуры и ускорению выполнения задач. Правильная организация информационных потоков приводит к тому, что API сайта предоставляет широкие возможности автоматизации последнего.

При этом отдельные компоненты REST функционируют примерно таким же образом, как взаимодействуют между собой серверы и клиенты в Интернете. Хотя работа систем на архитектуре REST до сих пор не имеет единого стандарта, большинство RESTful-реализаций используют конкретные стандарты, такие как HTTP, URL, JSON и XML. Здесь особенно важно, что открытый API – это возможность дополнения и расширения системы взаимодействия.

API для всех и каждого: создаем мощный парсер веб-сайтов без единой строки кода

Содержание статьи

Часто возникает задача периодически парсить какой-нибудь сайт на наличие новой информации. Например, если ты пишешь агрегатор контента с новостного сайта или форума, в котором нет поддержки RSS. Проще всего написать скрепер на Питоне и разобрать полученный HTML через beautifulsoup или регулярками. Однако есть более элегантный способ — самому сделать недостающие API для сайта и получать ответы в привычном JSON, как будто бы у сайта есть нативный API.

Не будем далеко ходить за примером и напишем парсер контента с «Хакера». Как ты знаешь, сайт нашего журнала сейчас не предоставляет никакого API для программного получения статей, кроме RSS. Однако RSS не всегда удобен, да и выдает далеко не всю нужную информацию. Исправим это!

Постановка задачи

Итак, наша задача: сделать API вида GET /posts , который бы отдавал десять последних статей с «Хакера» в JSON. Также нам нужно иметь возможность задавать сдвиг, то есть раз за разом получать следующие десять постов.

Ответ должен быть таким:

Также нужно иметь возможность получать следующие десять постов — со второй страницы, третьей и так далее. Это делается через GET-параметр вида GET /posts?page=2 . Если page в запросе не указан, считаем его равным 1 и отдаем посты с первой страницы «Хакера». В общем, задача ясна, переходим к решению.

Фреймворк для веба

WrapAPI — это довольно новый (пара месяцев от роду) сервис для построения мощных кастомных парсеров веба и предоставления к ним доступа по API. Не пугайся, если ничего не понял, сейчас поясню на пальцах. Работает так:

  1. Указываешь WrapAPI страницу, которую нужно парсить (в нашем случае главную «Хакера» — https://xakep.ru/).
  2. Говоришь, с какими параметрами обращаться к серверу, каким HTTP-методом (GET или POST), какие query-параметры передавать, какие POST-параметры в body, куки, хедеры. Короче, все, что нужно, чтобы сервер вернул тебе нормальную страничку и ничего не заподозрил.
  3. Указываешь WrapAPI, где на полученной странице ценный контент, который надо вытащить, в каком виде его представлять.
  4. Получаешь готовый URL для API вида GET /posts , который вернет тебе все выдранные с главной «Хакера» посты в удобном JSON!

Немного о приватности запросов

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

  1. Каждый API-репозиторий (а соответственно, и все API-запросы в нем) можно сделать приватным. Они не будут показываться в общем списке уже созданных API на платформе WrapAPI. Просто выбери достаточно сложное имя репозитория, и шанс, что на него кто-то забредет случайно, сведется к минимуму.
  2. Любой запрос к WrapAPI требует специального токена, который нужно получить в своей учетке WrapAPI. То есть просто так узнать URL к твоему репозиторию и таскать через него данные не получится. Токены подразделяются на два типа: серверные и клиентские, для использования прямо на веб-страничке через JavaScript. Для последних нужно указать домен, с которого будут поступать запросы.
  3. Ну и наконец, в скором времени разработчик обещает выпустить self-hosted версию WrapAPI, которую ты сможешь поставить на свой сервер и забыть о проблеме утечек данных (конечно, при условии, что в коде WrapAPI не будет бэкдоров).

Приготовления

Несколько простых шагов перед началом.

  1. Идем на сайт WrapAPI, создаем новую учетку и логинимся в нее.
  2. Устанавливаем расширение для Chrome (подойдет любой Chromium-based браузер), открываем консоль разработчика и видим новую вкладку WrapAPI .
  3. Переходим на нее и логинимся.

Это расширение нам понадобится для того, чтобы перехватывать запросы, которые мы собираемся эмулировать, и быстро направлять их в WrapAPI для дальнейшей работы. По логике работы это расширение очень похоже на связку Burp Proxy + Burp Intruder.

Для работы с WrapAPI нужно повторно авторизоваться еще и в расширении в консоли разработчика Chrome

Отлавливаем запросы

Теперь нужно указать WrapAPI, какой HTTP-запрос мы будем использовать для построения нашего API. Идем на сайт «Хакера» и открываем консоль разработчика, переключившись на вкладку WrapAPI.

Для получения постов я предлагаю использовать запрос пагинации, он доступен без авторизации и может отдавать по десять постов для любой страницы «Хакера», возвращая HTML в объекте JSON (см. ниже).

Запросы, которые генерятся по нажатию на ссылки пагинатора, будем использовать как образец

Чтобы WrapAPI начал перехватывать запросы, нажми Start capturing requests и после этого выполни целевой запрос (на пагинацию). Плагин поймает POST-запрос к странице https://xakep.ru/wp-admin/admin-ajax.php с кучей form/urlencoded-параметров в теле, в том числе и номером страницы. Ответом на запрос будет JSON-объект с параметром content , содержащий закешированный HTML-код с новыми постами. Собственно, этот блок и нужно парсить WrapAPI.

Запрос пойман, сохраняем его на сервер WrapAPI

Конфигурируем WrapAPI

После того как ты выбрал нужное имя для твоего репозитория (я взял test001 и endpoint posts ) и сохранил его на сервер WrapAPI через расширение для Chrome, иди на сайт WrapAPI и открывай репозиторий. Самое время настраивать наш API.

Обзор нашего будущего API

Переходи на вкладку Inputs and request. Здесь нам понадобится указать, с какими параметрами WrapAPI должен парсить запрашиваемую страницу, чтобы сервер отдал ему валидный ответ.


Конфигурируем входные параметры запроса

Аккуратно перебей все параметры из пойманной WrapAPI полезной нагрузки (POST body payload) в поле слева. Для всех параметров, кроме paginated , выставь тип Constant . Это означает, что в запросы к серверу будут поставляться предопределенные значения, управлять которыми мы не сможем (нам это и не нужно). А вот для paginated выставляй Variable API , указав имя page . Это позволит нам потом обращаться к нашему API по URL вида GET /posts?page=5 (с query-параметром page ), а на сервер уже будет уходить полноценный POST со всеми перечисленными параметрами.

Заголовки запроса ниже можно не трогать, я использовал стандартные из Chromium. Если парсишь не «Хакер», а данные с какого-нибудь закрытого сервера, можешь подставить туда нужные куки, хедеры, basic-auth и все, что нужно. Одним словом, ты сможешь настроить свой запрос так, чтобы сервер безо всяких подозрений отдал тебе контент.

Выставляем необходимые POST-параметры в формате form/urlencoded, чтобы наш запрос отработал правильно

Учим WrapAPI недостающим фичам

Теперь нужно указать WrapAPI, как обрабатывать полученный результат и в каком виде его представлять. Переходи на следующую вкладку — Outputs and response.

Продолжение доступно только участникам

Вариант 1. Присоединись к сообществу «Xakep.ru», чтобы читать все материалы на сайте

Членство в сообществе в течение указанного срока откроет тебе доступ ко ВСЕМ материалам «Хакера», увеличит личную накопительную скидку и позволит накапливать профессиональный рейтинг Xakep Score! Подробнее

Взаимодействие сервисов и REST API

В современной веб-разработке принято разделять backend-разработку (то, что выполняется на сервере – например, приложение на PHP) от frontend-разработки (то, что выполняется в браузере пользователя – JavaScript). Frontend выполняет запросы на backend и отрисовывает данные, которые backend ему возвращает. Но каким образом происходит этот обмен? Чем они обмениваются? Как выглядят данные, которые передаются между бэкендом и фронтендом? Об этом и пойдёт речь в данном уроке.

Продолжение урока будет доступно вам
после покупки курса PHP для профессионалов

Об авторе

Если вам интересно узнать
как я стал программистом,
читайте вот эту статью.

Что такое API? Простое объяснение для начинающих

Этот краткий термин на слуху у всех, кто хоть как-то сталкивался с разработкой. Но далеко не все понимают, что именно он обозначает и зачем нужен. Разработчик Пётр Газаров рассказал об API простыми словами в своём блоге.

Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений, программный интерфейс приложения). Большинство крупных компаний на определённом этапе разрабатывают API для клиентов или для внутреннего использования. Чтобы понять, как и каким образом API применяется в разработке и бизнесе, сначала нужно разобраться, как устроена «всемирная паутина».

Всемирная паутина и удалённые серверы

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

При введении в адресную строку браузера www.facebook.com на удалённый сервер Facebook отправляется соответствующий запрос. Как только браузер получает ответ, то интерпретирует код и отображает страницу.

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

API как способ обслуживания клиентов

Многие компании предлагают API как готовый продукт. Например, Weather Underground продаёт доступ к своему API для получения метеорологических данных.

Сценарий использования: на сайте небольшой компании есть форма для записи клиентов на приём. Компания хочет встроить в него Google Календарь, чтобы дать клиентам возможность автоматически создавать событие и вносить детали о предстоящей встрече.

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

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

Чем API Google Календаря отличается от API любого другого удалённого сервера в сети?

Технически, разница в формате запроса и ответа. Чтобы сгенерировать полную веб-страницу, браузер ожидает ответ на языке разметки HTML, в то время как API Google Календаря вернёт просто данные в формате вроде JSON.

Если запрос к API делает сервер веб-сайта компании, то он и является клиентом (так же, как клиентом выступает браузер, когда пользователь открывает веб-сайт).

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

Большинство современных сайтов используют по крайней мере несколько сторонних API. Многие задачи уже имеют готовые решения, предлагаемые сторонними разработчиками, будь то библиотека или услуга. Зачастую проще и надёжнее прибегнуть именно к уже готовому решению.

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

Таким образом, когда компания предлагает своим пользователям API, это просто означает, что она создала ряд специальных URL, которые в качестве ответа возвращают только данные.

Такие запросы часто можно отправлять через браузер. Так как передача данных по протоколу HTTP происходит в текстовом виде, браузер всегда сможет отобразить ответ. Например, через браузер можно напрямую обратиться к API GitHub (https://api.github.com/users/petrgazarov), причём без маркера доступа, и получить вот такой ответ в формате JSON:

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

Ещё несколько примеров API

Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает:

  • фрагмент программного обеспечения с определённой функцией,
  • сервер целиком, приложение целиком или же просто отдельную часть приложения.

Любой фрагмент ПО, который можно чётко выделить из окружения, может заменять букву «А» в англоязычной аббревиатуре, и тоже может иметь некоторого рода API. Например, при внедрении в код разработчиком сторонней библиотеки, она становится частью всего приложения. Будучи самостоятельным фрагментом ПО, библиотека будет иметь некий API, который позволит ей взаимодействовать с остальным кодом приложения.

В объектно-ориентированном проектировании код представлен в виде совокупности объектов. В приложении таких объектов, взаимодействующих между собой, могут быть сотни. У каждого из них есть свой API — набор публичных свойств и методов для взаимодействия с другими объектами в приложении. Объекты могут также иметь частную, внутреннюю логику, которая скрыта от окружения и не является API.

API сервисы

Знакомство с API
Базовая информация о принципах работы API Rosreestr и о подготовке к его использованию

Получение доступа
Инструкция по получению ключа доступа для работы со всеми методами API


Запросы к API
Выполнение запросов к API Rosreestr. Общие параметры, синтаксис запроса и рекомендации

Webhooks
Принцип работы Webhooks, подключение и пример использования

Версии API
Последние обновления и изменения в версиях API

Как работать с API без знаний программирования: применяем опыт топ-агентств по SEO

Почему не нужно бояться API

Как сервис с сотней тысяч клиентов мы каждый день сталкиваемся с проблемой — SEO-специалисты боятся работать с API либо не видят преимуществ. Только прогрессивные агентства по интернет-маркетингу и крупный бизнес выбирают работу с API. Основная причина этому — обработка полученных данных, так как они выгружаются в формате JSON и выглядят вот так:

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

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

Плюсы работы с API

  1. Ускоряет работу в 10 раз. Даже самый дешевый план открывает доступ к API со скоростью парсинга 1 запрос/секунда. Максимальная скорость — 10 запросов/секунда. Сможете ли вы столько ввести руками? Разумеется, нет. Поэтому большие агентства с постоянной работой по семантике пользуются API.
  2. Больше лимитов. Независимо от тарифного плана API-лимитов всегда больше, чем запросов в интерфейсе. Это значит, что за те же деньги, получаете больше данных. Плюс у вас остаются нетронутыми лимиты для интерфейса.
  3. Индивидуальные отчеты. Используя API, вы можете совместить несколько отчетов в один и сортировать полученные данные всего одной командой для автоматизации ваших задач.
  4. Экономит деньги. Используя API, вы платите только за полученные результаты, а не за использование лимитов вашего тарифного плана.

Как начать работу с API Serpstat

Первая версия инструмента предназначена для работы с 16 отчетами из базы данных Serpstat.

  1. Advertising report — выполняет поиск рекламных объявлений по ключевой фразе.
  2. Competitors report — возвращает конкурентов по заданной ключевой фразе.
  3. Domain history report — возвращает историю изменения видимости и количества фраз по домену.
  4. Domain info report — возвращает суммарную информацию по домену (количество запросов/видимость в поиске/контексте, динамику изменения количества запросов/видимость, тематики домена).
  5. Domain Keywords report — возвращает ключевые слова в ТОПе поисковой системы по домену.
  6. Domain Intersection report — возвращает общие ключевые слова для доменов.
  7. Domain unique keywords report — возвращает ключевые слова домена без учета ключевых слов второго (третьего) домена.
  8. Domain urls report — возвращает URL-ы домена и количество ключевых слов для URL-а.
  9. Keyword info report — возвращает данные по ключевому слову (количество запросов, стоимость за клик, уровень конкуренции, категории).
  10. Keywords report — выполняет полнотекстовый поиск по ключевому слову и предоставляет данные по найденным ключевым словам (количество запросов, стоимость за клик, уровень конкуренции).
  11. Keyword top report — возвращает последний ТОП по ключевой фразе.
  12. Related keywords report — возвращает похожие запросы.
  13. Suggestions report — выполняет полнотекстовый поиск по поисковым подсказкам.
  14. URL competitors report — возвращает URL конкурентов для заданного URL.
  15. URL keywords report — возвращает ключевые фразы в ТОПе поисковой системы по заданному URL.
  16. URL missing keywords report — возвращает ключевые фразы, по которым ранжируются конкуренты, но которые отсутствуют в заданном URL.

Пошаговая настройка скрипта

Чтобы подготовить инструмент к работе, следуйте инструкции.

    Откройте документ и создайте копию у себя на диске. Подождите появления кнопки Configure и кликните на нее. Затем «Установить ключ API».

Подтвердите разрешение для запуска документа и свяжите его с вашим Gmail-аккаунтом.

Вставьте ваш API-токен, который находится в профиле пользователя Serpstat.

Бесплатный доступ к API может получить каждый пользователь Serpstat.

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

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

Больше бесплатных скриптов для API Serpstat

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

Поиск форумов для линкбилдинга

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

Инструмент в разы экономит время линкбилдеров, которым больше не нужно собирать форумы руками с помощью операторов intitle, inurl и т.д.

Поиск тематических блогов

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

Сбор семантики и анализ URL конкурентов

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

Принцип работы автор скрипта подробно описал в этой статье.

Поиск дропов по WHOIS

Задача скрипта — достать домены из ниши и определить зарегистрирован ли домен, если да — то дату начала и окончания регистрации домена. Для этого используется бесплатная библиотека phpWhois.

Поиск нецелевых страниц для контекстной рекламы

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

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

Как еще используют API?

Компания ArtJocker использует API Serpstat для постановки KPI SEO-специалистам. Система работает следующий образом:


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

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

Эти показатели проверяются калькулятором KPI от ArtJocker на совместимость с общей картиной по сайту. Со слов руководителя отдела маркетинга, погрешность не более чем в 5–10%.

Напоследок

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

Руководство по построению HTTP API

Введение

Данное руководство содержит рекомендации по проектированию HTTP API, которые были почерпнуты из работы API облачной платформы Heroku, кроме того, оно также содержит информацию о новом функционале и внутреннем API в Heroku.

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

При прочтении данной статьи подразумевается, что вы знакомы с основными принципами HTTP и JSON.

Основы

Принцип разделения ответственности

При проектировании старайтесь сохранять простоту системы, разделяя ответственность между различными частями цикла «запрос-ответ». При этом простота принимаемых решений позволит концентироваться на решении все более сложных задач. Запросы и ответы выполняются для получения доступа к определенному ресурсу или набору ресурсов. Для определения сущности, которую необходимо получить, используйте путь и тело ответа для передачи содержимого, а заголовки – для передачи метаданных. Можно передавать все параметры в теле запроса, но, как показывает практика, такое решение является менее гибким. Более правильным подходом будет передача части параметров в заголовках.

Требуйте использования защищенных соединений

Для получения данных при помощи API используйте только защищенные соединения с TLS.
Лучше решением было бы отклонять все запросы, не использующие TLS, а именно запросы по http или на 80-ый порт, во избежание небезопасного обмена данными. В случаях, когда это невозможно, отдавайте ответ 403 Forbidden .

15–16 ноября, Минск, 133–390 br

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

Требуйте наличие версии в заголовке Accept

Наличие нескольких версий и переходы между ними может быть одним из самых сложных аспектов проектирования и использования API. Поэтому лучше заранее учесть этот момент.

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

Лучше всего – добавить версию в заголовок вместе с другими метаданными, используя заголовок Accept с пользовательским типом содержимого:

Используйте заголовок ETags для кеширования

Включайте заголовок ETags во все запросы, определяя при этом версию возвращаемого ресурса. Это позволит пользователям кэшировать ресурсы и реализовывать условные запросы при помощи использования заголовка If-None-Match , который поможет определить, нужно обновлять кэш или нет.

Используйте Request-ID для интроспекции

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

Разделяйте большие ответы сервера на несколько небольших при помощи заголовка Range

Большие ответы необходимо разбивать на более мелкие, используя заголовок Range . Для получения более детальной информации о заголовках запросов/ответов, кодах состояний и ограничениях изучите Обсуждение использования заголовка Range в API платформы Heroku .

Запросы

Возвращайте соответствующие коды состояний

Возвращайте соотвествующий код состояния HTTP в каждом ответе. Успешные ответы должны содержать такие коды состояний:

  • 200 – GET запрос завершился успешно, синхронный DELETE или PATCH запрос завершился успешно или синхронный PUT запрос обновил существующий ресурс.
  • 201 – Синхронный POST запрос завершился, синхронный PUT запрос создал новый ресурс.
  • 202 – Принят POST , PUT , DELETE или PATCH запрос, который будет обработан асинхронно.
  • 206 – GET запрос завершился успешно, но будет возвращен частичный ответ (см. раздел про заголовок Range ).

Обратите внимание на использование кодов состояния ошибок авторизации и аутентификации:

  • 401 Unauthorized – запрос завершился с ошибкой, поскольку пользователь не прошел аутентификацию.
  • 403 Forbidden – запрос завершился с ошибкой, так как пользователь не авторизовался для получения доступа к определенному ресурсу.

Возвращайте соответствующие коды ошибок для предоставления дополнительной информации об их причинах:

  • 422 Unprocessable Entity – Ваш запрос был распознан, но содержит неверные параметры.
  • 429 Too Many Requests – Превышен лимит запросов, попробуйте позже.
  • 500 Internal Server Error – Проблема на стороне сервера, проверьте состояние сайта и/или сообщите о проблеме.

Для получения более подробной информации о кодах состояния HTTP изучите спецификацию.

По возможности, предоставляйте полные версии ресурсов

Возвращайте пользователям вашего API полное представление ресурса (то есть объект со всеми атрибутами) во всех ответах, где это возможно. Всегда предоставляйте полную версию ресурса в ответах на запросы с кодами состояния 200 и 201 , включая PUT , PATCH и DELETE запросы.


Ответы на запросы с кодом состояния 202 не должны содержать все поля объекта

Ваш API должен принимать сериализованный JSON в теле запроса

Ваш API должен предусматривать возможность передачи сереализованного JSON в теле PUT / PATCH / POST запросов вместо, либо в дополнение к передаваемым данным формы. Таким образом создается симметрия в JSON-ответах:

Будьте последовательны при конструировании пути к ресурсу

Названия ресурсов

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

Действия

Старайтесь проектировать такие конечные url, которые не требуют дополнительных действий для отдельных ресурсов. В случаях, когда это необходимо, добавляйте в общий путь компонент «action» для того, чтобы четко определить эти действия:

Используйте названия компонентов пути и атрибутов в нижнем регистре

Для названий компонентов пути к ресурсу используйте нижний регистр и разделяйте их при помощи дефиса.

Названия атрибутов лучше писать в нижнем регистре, а в качестве разделителя лучше использовать нижнее подчеркивание – таким образом названия полей можно писать без скобок в Javascript:

Ваш API должен поддерживать доступ к ресурсу не только по его id

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

Сведите к минимуму количество вложений в пути для доступа к ресурсу

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

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

Ответы

Предоставляйте UUID запрашиваемых ресурсов

У каждого ресурса по умолчанию должен быть атрибут id . В качестве значений идентификатора ресурса старайтесь всегда использовать UUID. Не используйте идентификаторы, которые не будут уникальными в масштабе вашего сервиса, особенно автоинкрементные идентификаторы.
UUID ресурса выводите в формате 8-4-4-4-12:

Предоставляйте информацию о дате создания и изменения ресурса

По умолчанию ресурс должен хранить информацию о дате его создания created_at и обновления updated_at .

Временные величины должны быть форматированы согласно ISO8601

Принимайте и возвращайте временные данные только в UTC, а выводите в формате ISO8601:

Отношения с внешними сущностями должны быть вынесены во вложенный объект

Внешние отношения должны быть сериализованы как вложенный объект:

А не как поле объекта:

Такой подход позволяет добавить больше информации о связанном объекте без необходимости менять структуру ответа:

Создавайте структурированные ответы в случае возникновения ошибок

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

Показывайте ограничение по количеству запросов

Ограничение по количеству запросов вводится для поддержания работоспособности системы и возможности качественного обслуживания других клиентов. Для расчета ограничений на количество запросов можно использовать алгоритм текущего ведра. Возвращайте оставшееся количество запросов для каждого запроса в заголовке ответа RateLimit-Remaining .

JSON во всех ответах должен быть минимизирован

Лишний пробел увеличивает размер ответа и многие Javascript клиенты для удобочитаемости автоматически отформатируют JSON. Поэтому лучше минимизировать JSON ответы:

Вы можете опционально добавить возможность получать более развернутый ответ, указывая дополнительный параметр (например, ?pretty=true ) или задавая значения для заголовка Accept ( Accept: application/vnd.heroku+json; version=3; indent=4; ).

Артефакты

Предоставляйте удобную для обработки JSON-схему

Для точного описания вашего API предоставляйте JSON-схему. Для управления схемой используйте prmd, также удостоверьтесь в том, что она проходит валидацию при помощи команды prmd verify .

Предоставляйте удобочитаемую документацию

Для того, чтобы разработчики разбирались в принципах работы вашего API, предоставьте им удобную документацию. Если вы создали JSON-схему, используя prmd , как описано выше, вы можете легко сгенерировать Markdown документацию для всех конечных url, используя команду prmd doc .

Вдобавок к описанию конечных url, предоставьте обзор API, включая туда следующую информацию:

  • процесс аутентификации – получение и использование пользовательского токена;
  • стабильность API и его версию, а также информацию о том, как выбрать нужную версию API;
  • общие заголовки запросов и ответов;
  • формат выдачи ошибки;
  • примеры использования API с клиентами на разных языках;

Предоставляйте примеры запросов, которые можно протестировать

Предоставляйте примеры запросов, которые пользователи могут протестировать. Для тестирования этих запросов пользователь должен выполнить минимум действий:

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


Опишите стабильность вашего API

Вы можете описать степень стабильности вашего API или отдельных конечных url при помощи установки флагов prototype / development / production .

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

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

Как подружить маркетолога с API и самому научиться делать интеграции

Содержание:

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

Кому будет полезно

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

Чем поможет этот навык

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

На пальчиках — что такое API

API проще понять на примере. Чтобы соединить два устройства, вы используете кабель или любую другую беспроводную связь, причем эта связь имеет за собой определенную функциональность: передача данных, синхронизация и тд. Кабель или Bluetooth работают словно API-интерфейс: соединяют две или более систем для достижения определенной цели или функциональности. Такую связь называют интеграцией.

Несколько близких примеров интеграций: коллтрекинг, отправка лидов в CRM, сбор данных для Google Analytics — все эти примеры используют Javascript API, хоть это и не относят к интеграциям.

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

Итак, API — это набор функций, который связывает (интегрирует) программные продукты. Это не точное определение, но достаточное для понимания маркетологу его задач.

Иногда вы можете встретить API c добавкой «REST». REST — это просто стандарт, не более того. Не обращайте на это внимания.

Начинаем разбираться

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

Почти все API популярных сервисов построены на http-запросах. Давайте начнем именно с них. Почти каждый раз, когда вы заходите на какой либо сайт: http://carrotquest.io , вы совершаете http-запрос по адресу: carrotquest.io. Ваш браузер получает в ответ содержание, которое вы видите в браузере при загрузке страницы.

HTTP — это протокол передачи данных. Изначально предназначенный для передачи гипертекстовых документов (то есть документов, которые могут содержать ссылки, позволяющие организовать переход к другим документам).

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

Но есть небольшое отличие от бумажной рассылки писем — адресат всегда отправляет уведомление о получении. Такую роль выполняют статусы. Вы наверняка встречались с “ошибкой 404” или “502 bad gateway” при загрузке веб-страниц в браузере. Это и есть статус. Кроме того, адресат вместе со статусом может отправить подробности. Например, что ошибка в параметрах или эта версия API устарела.

Вообще, про статусы вам нужно знать главное: 200 ОК — все хорошо, запрос ушел без ошибок; любой другой, который начинается не с 2**, надо гуглить. Вот список всех статусов .

Теперь поговорим про содержание. В случаях, когда вы загружаете веб-страницу, вы получаете в содержании HTML. Работая с API, вы будете в основном работать с JSON или XML. Иногда в качестве содержания бывает просто текст, такое тоже возможно.

Почти в 90% случаев в качестве содержания в запросе будет формат JSON. Поэтому в основном вы будете работать именно с ним. Также стоит познакомится с форматом XML. Ваша задача самостоятельно изучить материал про эти форматы в статьях ниже. Причем не обязательно разбираться, как оперировать данными в содержании, но обязательно понимать структуру и какие данные есть.

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

Что вы должны знать из статей:

  1. из чего состоит структура запроса,
  2. что такое POST и GET, чем отличаются,
  3. какие структуры данных можно отправлять в запросе,
  4. что такое JSON, XML.

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

Заглянем в API

Почти в каждом API есть слово «методы» — это, грубо говоря, функциональная возможность API. Например, вот так выглядят методы в amoCRM.

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

Довольно часто, копаясь в API, вы можете встретить классификацию методов по GET и POST. Для нас это подсказка, что в GET мы получаем данные, а в POST изменяем данные внутри, создавая, дополняя или перемещая информацию.

Заглянем в один из методов. Откроем метод «Записать событие» в Carrot developers:

Иногда при отправке запроса нужно передать обязательную дополнительную информацию. Как в данном методе: идентификатор пользователя, название события.

Вроде, все логично:

Название события (event) — у созданного события должно быть имя.


Идентификатор пользователя (ID) — пользователь, в которого нужно записать событие.

НО здесь может быть справедливый вопрос: где мне взять id пользователя, чтобы записать в него событие?

Вам нужно об этом позаботится заранее. Отправляя запрос, у вас должен быть доступ к нужному id пользователя. Например, вы хотите отправлять события из AmoCRM в Google Analytics, что у пользователя изменился статус сделки. Для этого нужно, чтобы в amoCRM в сделке был записан client_id пользователя. Один из способов взять client_id — отправить вместе с заявкой, взяв client_id из cookie пользователя.

Рассмотрим метод более детально.

  • URL — адрес, на который отправляем запрос.
  • Аргументы — данные, которые отправляем в запросе.
  • Ответ — после отправки мы всегда получаем ответ. Напоминаем, что 200 — это ОК, запрос успешно отправлен. Другой статус с ‘error’ — ошибка. Вы можете загуглить ошибку и разобраться, в чем проблема.

Мы рекомендуем всегда передавать аргументы в виде структуры JSON. Это выдерживает стиль и не создают путаницу. + Низкая вероятность ошибки в синтаксисе:

Webhook и микросервисы

Не во всех API сервисов это есть, но можно встретить. Webhook — механизм оповещения системы о событиях. Для нас это по-прежнему обычный http-запрос за исключением того, что писать код для отправки запроса не нужно — нужно выбрать триггер для его отправки и адрес.

Например, в amoCRM это может быть смена статуса сделки, а в Carrot quest — определенное событие пользователя.

Webhook содержит определенную структуру JSON — она неизменна. Обычно в API описано, какую структуру содержит Webhook. Попробуйте для себя поискать в разных API сервисов структуру вебхука.

Справедливый вопрос: что мне делать с этой структурой, если она не подходит ни под одно API и вообще не подходит мне?

Любую структуру можно преобразовать в новый запрос, который подходит под API другого сервиса. По сути, задача сводится к следующему: взять данные из вебхука, собрать эти данные в новый запрос под определенный метод другого API. Таким посредником обычно служит отдельно написанный код (так называемый микросервис), который принимает вебхуки и отправляет новые запросы.

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

Кроме того, существуют облачные решения для интеграций. Например, AWS Lambda.

Где еще понадобятся микросервисы

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

Готовые или «однокнопочные » интеграции как раз и есть такие же микросервисы, которые объединяют два разных API, но с интерфейсом и возможностью задавать свои настройки.

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

Где не понадобятся микросервисы

Если вам не нужно связывать два разных API, то запрос достаточно сформировать от отправителя. Разберем это опять на примере интеграции «Отправка лидов в CRM из форм сайта». В данном случае запрос формируется и исполняется на стороне браузера пользователя, когда он оставляет заявку.

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

Javascript API

Если сервис работает с вебом, то, скорее всего, у него оно есть. JS API расширяет возможности работы с сайтом и его пользователями. Частый случай использования в Carrot quest — запись свойств и событий с сайта, которые нельзя собрать, используя стандартные возможности мастера сбора данных.

Здесь есть два пути.

Вы можете научиться навыкам программирования на JS. Уж совсем минимального уровня может хватить, но только в краткосрочной перспективе и не под все задачи, а так вполне задача под силу. Но начинать сразу с этого не стоит — посмотрите на вариант ниже.

Попробуйте сначала научится разбираться в документации JS API, как все устроено. Не нужно запоминать код. Обратите внимание, что как и в случае с HTTP, у JS API тоже есть методы и параметры к ним. Исходя из этих методов, вы научитесь понимать возможности. Этого будет достаточно для составления ТЗ разработчику, и, возможно, вам не потребуется разбираться в программировании на JS.

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

Другие API

Так сложилось, что разным классам возможностей API дают свои имена: Data API, Call API. Почти всегда это частный случай API с HTTP-запросами, который вынесли в отдельный класс, потому что он отличается по назначению. Но бывают исключения, например, в Carrot quest URL API: https://carrotquest.io/developers/urlapi/

Кроме того, нужно сказать, что есть API с другими протоколами — не с HTTP. Например, SMPP. Их часто можно встретить в SMS-сервисах.

Дополнительно. Навыки в программировании

Для работы с API мы рекомендуем Python и JavaScript. И это не только для API, в целом это хорошее сочетание, чтобы делать прикладные программы, парсеры и тд. Начните с Python.

Python — язык довольно простой и понятный, в отличии от других, имхо. Очень богат пакетами под разные задачи. Плюс это популярный язык в Data science и вообще, один из основных инструментов для работы с данными, если не самый основной. Конечно, если вы захотите двигаться в этом направлении. И, наверное, самый простой в изучении.

С чего начать

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

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

План обучения быть таким:

  1. Основные возможности языка Python;
  2. Работа с пакетами.

Пакеты — это набор готовых функций для работы с чем-то. Например, requests содержит функции для отправки запросов. Навык в Python можно оценить по тому, насколько хорошо ты разбираешься в пакетах. Правда, это не обязательно — всегда можно загуглить, но скорость увеличивается кратно.

Рекомендую парочку курсов:

Must-have пакеты для работы с API:

  • Requests — пакет для работы с HTTP-запросами.
  • Json — пакет позволяет кодировать и декодировать данные в удобном формате.
  • Может пригодится, если нет возможности работать с JSON:
  • xml.etree.ElementTree — для работы с XML-структурами.

Javascript

В основном нужен для работы с вебом абсолютно под разные задачи. Рекомендуем ознакомиться лишь поверхностно, чтобы разбираться в API. И вот почему. Без основ HTML и CSS это будет бесполезно и сложно. Все равно эти основы понадобятся.

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

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

  1. Основы Javascript. Основные кирпичики, из которых состоят скрипты.
  2. Объекты, прототипы, методы. Нужно просто знать, что это и как с этим работать.
  3. DOM, браузерные события, формы, элементы управления, как отправить http-запрос, работа с cookie + параллельно изучаете библиотеку jQuery. Это важно. Так как вы будете понимать, что вы можете сделать с помощью jQuery, а в каких случаях делать все на чистом JS. Во-вторых, все запоминать не придется. Главное — ориентироваться.

А дальше зависит от того, какие задачи вы хотите решать. Тот план, что выше, в 95% случаев подходит под задачи с API.

С курсами так же как и с Python: возьмите несколько и изучайте параллельно. Необязательно всегда идти по порядку курса. Забегать вперед даже полезно. Но парочку курсов можно выделить:

Хозяйке на заметку

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

Напоследок

Не надо начинать с программирования. Попробуйте разобраться с тем, что вы узнали из этой статьи. Потом, когда вы поймете, что вам этого мало — welcome! Очень важно, чтобы ваши навыки в программировании были использованы в реальных задачах , иначе все зря. Иначе вы забудете это, как курс высшей математики, если это не ваша область.

Илон Маск рекомендует:  Что такое код swfbitmap &#62;getwidth
Понравилась статья? Поделиться с друзьями:
Кодинг, CSS и SQL