REST API — частный случай API
Допустим, мы написали сайт на PHP (Python, Java — не принципиально). PHP генерирует контент на сервере и по сети нам отправляет обратно уже сгенерированный HTML, JavaScript и CSS. Создавая сайт на PHP, вы получили некую статику, напрямую связывая код PHP, стили, HTML. Он взаимодействует с базой данных и выводит данные в шаблон. Предположим, мы задались целью разработать мобильное приложение под данную систему. Мобильное приложение должно работать с той же базой данных и мы должны как-то присоединить его к уже существующей системе.
Раньше многие шли по такому пути — создавали API для системы «сайт плюс база данных», и мобильное приложение работало через API или непосредственно через сам сайт. Но поддерживать и расширять такую концепцию было неудобно, поэтому постепенно перешли к варианту, когда используется связка backend и frontend. Backend по-прежнему работает с базой данных, а frontend является вообще отдельным приложением, которое, грубо говоря, ничего не знает про backend. Frontend является абстрагированный клиентом и может быть написан на Angular, React, Vue или просто на JavaScript.
Если для сайта имеется мобильное приложение, оно также относится к разряду клиентов и общается с backend-частью посредством API. При такой схеме клиентов может быть сколько угодно — мобильный клиент для Android, приложение под iOS, десктопное приложение, админка сайта и т. д. Частным случаем такой организации является REST API (Representational State Transfer) — некий стандартизированный протокол, позволяющий перемещать state и обмениваться им по API. Впервые его описал в своей диссертации Рой Филдинг. В ней он предложил соединять разные части программы либо сервисы по HTTP.
Интеграция 1С с ГИИС ДМДК
ГИИС ДМДК — единая информационная платформа для взаимодействия участников рынка драгоценных металлов и драгоценных камней. с 01.09.21 стартовал обязательный обмен данными с Федеральной пробирной палатой (ФПП) исключительно через ГИИС. А постепенно — с 01.01.2022 и с 01.03.2022 — все данные о продаже драгоценных металлов и камней должны быть интегрированы с ГИИС.
У многих пользователей возникает вопрос как автоматизировать обмен между программой 1С и ГИИС ДМДК.
В настоящей статье ВЦ Раздолье поделится своим опытом о реализации такого обмена.
Автор статьи — Мордовин Антон — архитектор систем на базе 1С Внедренческого центра «Раздолье».
Что такое программный интерфейс приложения (API)
Перед тем, как начать разговор о REST API, давайте вспомним, что такое API и для чего он нужен. API расшифровывается как Application Program Interface — программный интерфейс приложения. Данное понятие применимо не только к веб-разработке, но и к любым программным продуктам вообще. Наушники, микроволновые печи, телевизоры, микропроцессоры — все они имеют свой API.
Предположим, мы имеем дело с двумя такими совершенно разными разработками, каждая из которых обладает своим собственным API. Эти системы должны как-то взаимодействовать между собой, но есть некоторая сложность — ведь каждая из систем разработана на своем языке, по своим стандартам, со своими драйверами, на своей операционной системе и так далее. Чтобы как-то привести эти системы к общему знаменателю и иметь возможность коммуникации, мы используем API как некие внешние рычаги, которые влияют на внутреннее состояние каждой из систем. По этому принципу работает огромное количество проектов.
API как уровень абстракции
Когда речь идет о ПО, API нужно везде. API идет рука об руку с одним из самых фундаментальных концептов в компьютерной науке — абстракцией.
Абстракция — способ организовать сложную систему так, что сложные действия могут выполняться просто.
Пример такой абстракции — программируемая облачная кнопка Amazon Dash Button. Ее можно настроить, чтобы подсчитывать или отслеживать предметы, звонки или сообщения, чтобы включать и выключать определенные действия
Можно выбрать внешний вид облачной кнопки Amazon
Вы заказываете кнопку Dash Button на Amazon и используете приложение на смартфоне, чтобы подключить кнопку к вашей сети Wi-Fi, учетной записи на Amazon и например, к вашей любимой марке бумажных полотенец.
Затем когда вы захотите заказать бумажные полотенца, жмете на кнопку. Она подключится к интернету и отправит сообщение, чтобы заказать их из вашей учетной записи Amazon. Через несколько дней вам доставят бумажные полотенца.
Как и API, Dash Button — это простой интерфейс, который прячет свою сложность от пользователя. Идентификатор продукта, который вы заказали, должен быть извлечен из базы данных. Ваш адрес доставки должен быть извлечен из вашей учетки, ближайший к вам склад с полотенцами нужно уведомить о заказе, а еще отгрузить нужный продукт со склада и упаковать. Затем товар нужно доставить по маршруту вместе с другими посылками.
Теперь представьте, что вам как клиенту пришлось бы координировать всё это.
Вы бы никогда не заказали бумажные полотенца, потому что это слишком трудозатратно.
К счастью, все эти муки спрятаны от вас. За тем, чтобы вам доставили полотенца, стоит длинная связанная цепь компьютерных систем и координации людей. А вам нужно только нажать на кнопку.
Методы решения проблем
Какие есть методы решения проблем?
Самый простой вариант – вам предоставят тестовый стенд. Вам выделяют отдельную область, в которой вы будете тестировать свои алгоритмы.
В чем тут может быть проблема? Если стенд один, а разработчиков несколько – ваши тесты могут мешать друг другу.
Следующий вариант – написать свой сервер.
Все программисты, если что-то не работает на стороне, начинают писать свое. Делаем небольшой сервер – берем Python или OneScript.Web – и пишем небольшие заглушки. Мы знаем, какие запросы отправляем, готовим под них ответы.
В чем здесь проблема? Его надо писать. Это будет ваше отдельное приложение, которое надо поддерживать.
Следующий вариант – использовать специальные mock-сервера (заглушки).
Для них все равно нужно будет готовить данные.
При этом вам нужно не забывать за этими данными следить – вы поставили заглушку, у вас тестирование прекрасно проходит, но если на «боевой» уже поменялся API, и у вас тестируется не реальная ситуация.
Mock-сервер можно использовать только для тестов. Никаких альфа-бета-тестирований на mock-сервере проводить не стоит – для этого нужно использовать только боевой контур.
Последний вариант – решить все архитектурно, написать приложение так, чтобы оно само в себе содержало тестовые данные и могло их в любой момент использовать. Это самый сложный вариант, мы не будем на нем останавливаться
Мы разберем мокирование.
Что такое API и что собой представляет Windows API.
Опубликовал(а): Vital
в: 7 ноября 2011
Введение в API-программирование
API (application programming interface) — интерфейс прикладного программирования (иногда интерфейс программирования приложений). Другими словами, это те возможности (функции, переменные, константы, классы), которые предоставляет приложение для использования прикладными программами.
API определяет функциональность, которую предоставляет программа (модуль, библиотека), при этом API позволяет абстрагироваться от того, как именно эта функциональность реализована.
Если программу (модуль, библиотеку) рассматривать как чёрный ящик, то API — это множество «ручек», которые доступны пользователю данного ящика, которые он может вертеть и дёргать, при этом ящик будет производить какието определенные действия понятные и необходимые пользователю, но пользователь, при этом, не имеет даже представления о их реализации.
Программные компоненты взаимодействуют друг с другом посредством API. При этом обычно компоненты образуют иерархию — высокоуровневые компоненты используют API низкоуровневых компонентов, а те, в свою очередь, используют API ещё более низкоуровневых компонентов.
API операционных систем.
Практически все операционные системы (Unix, Windows, Mac OS, и т. д.) имеют API, с помощью которого программисты могут создавать приложения для этой операционной системы. Главный API операционных систем — это множество системных вызовов.
В индустрии программного обеспечения общие стандартные API для стандартной функциональности имеют важную роль, так как они гарантируют, что все программы, использующие общий API, будут работать одинаково хорошо или, по крайней мере, типичным привычным образом. В случае API графических интерфейсов это означает, что программы будут иметь похожий пользовательский интерфейс, что облегчает процесс освоения новых программных продуктов.
Widows API
Windows API — общее наименование целого набора базовых функций интерфейсов программирования приложений операционных систем семейств Windows (от Windows 3.11 до Windows 98) и Windows NT корпорации «Microsoft». Является самым прямым способом взаимодействия приложений с Windows. Для создания программ, использующих Windows API, «Microsoft» выпускает SDK, который называется Platform SDK и содержит документацию, набор библиотек, утилит и других инструментальных средств.
Windows API был изначально спроектирован для использования в программах, написанных на языке C (или C++). Работа через Windows API — это наиболее близкий к системе способ взаимодействия с ней из прикладных программ. Более низкий уровень доступа, необходимый только для драйверов устройств, в текущих версиях Windows предоставляется через Windows Driver Model.
Win32 – 32х разрядный API для современных версий Windows. Самая популярная ныне версия. Базовые функции этого API реализованы в DLL kernel32.dll и advapi32.dll; базовые модули GUI — в user32.dll и gdi32.dll. Win32 появился вместе с Windows NT и затем был перенесён (в несколько ограниченном виде) в системы серии Windows 9x. В современных версиях Windows, происходящих от Windows NT, работу Win32 GUI обеспечивают два модуля: csrss.exe (Client/Server Runtime Subsystem), работающий в пользовательском режиме, и win32k.sys в режиме ядра. Работу же системных Win32 API обеспечивает ядро — ntoskrnl.exe
Win64 — 64-разрядная версия Win32, содержащая дополнительные функции для использования на 64-разрядных компьютерах. Win64 API можно найти только в 64-разрядных версиях Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, Windows Server 2008 R2 и Windows 7.
Структура API-программ
Центральным понятием программирования в среде Windows является сообщение. Система посылает сообщение приложению, а то, в свою очередь, должно правильно отреагировать на него. Получателями сообщений являются функции окон приложения, на программирование которых и уходит большая часть времени при разработке API-приложений.
Классическая структура API-программы определяется четырьмя компонентами: инициализация; цикл ожидания, или цикл обработки сообщений; функция главного окна; другие функции. В простейшем случае последний компонент может отсутствовать. Два первых компонента располагаются в функции WinMain, остальные реализуются отдельными функциями.
Виды API
Публичные API выпускаются такими компаниями, как Slack и Shopify, в надежде на то, что разработчики будут их использовать на своих платформах. Компании делятся набором вводных параметров, которые разработчики используют, чтобы достичь какого-то результата.
Публичное API можно использовать без проблем — доступ к документации можно получить без проблем.
Приватные API используются внутри компании. Если у компании много программных продуктов, приватное API используется, чтобы программы разговаривали между собой. Компоненты API могут меняться по желанию компании, тогда как изменения в публичном API может вызвать отчаянные протесты.
Давайте рассмотрим Java API и Twitter API в качестве примеров. Эти API относятся к виду публичных.
Java API
Java API — библиотека компонентов ПО доступных в готовом виде всем, кто установил Java Development Kit. Эти компоненты выполняют общие задачи и повышают производительность, так как программистам не нужно писать код с нуля каждый раз.
Один из базовых компонентов в ПО называется List, или Список. Этот компонент следит за списком сущностей. Java API определяет, что вы можете делать со списком: добавлять сущности, сортировать их в списке, определять, входит ли сущность в список. API также уточняет, как выполнять эти действия. Чтобы отсортировать список, вам нужно уточнить, какую сортировку вы хотите: по алфавиту, количественно, по цвету.
для метода сортировки Списка. Сравнитель — это параметр, который определяет сортировку списка
Twitter API
Twitter API, вместе со многими другими API в веб-версии, — пример REST API. REST API — это API, которое использует архитектурный стиль, основанный на передаче состояния представления. REST — это стиль строительных систем, который обеспечивает гибкое общение и отображение информации в вебе.
В REST API ресурс может быть чем угодно.
Примеры ресурсов: пользователь, список твитов, результаты поиска твитов. К каждому из этих ресурсов можно обращаться по его идентификатору. В случае REST API в веб-версии — это обычно URL.
Когда приложение запрашивает ресурс через идентификатор, API отдает текущее представление ресурса приложению в подходящем для него формате: в JPEG, HTML-странице или JSON.
Одна из отличительных характеристик REST — это то, что API отправляет данные приложению, которое их запрашивает. Несмотря на то, что это дает гибкость приложению, эта гибкость достигается ценой снижения эффективности. Пересылать данные в вебе для обработки — довольно медленный процесс.
Тестируйте VPS-сервер первые 30 дней за $1
Тестировать за $1
- Память: 2048 МБ
- Диск: 20 ГБ SSD
- Трафик: Безлимит
- CPU: 2 ядра
Недостатки REST API
Минус этого архитектурного стиля состоит в том, что он завязан на HTTP. Спецификация HTML имеет ограничения и формы, отправляющие данные могут быть реализованы только через GET или POST. Поэтому для корректной работы с другими методами их приходится имитировать. Например, в Rack (механизм на базе которого Ruby взаимодействует с веб-сервером; с использованием Rack сделаны Rails, Merb и прочие Ruby-фреймворки) в форму можно прописать hidden-поле с именем “_method”, а в качестве значения указать имя метода (скажем, «PUT») — при этом будет отправлен POST-запрос, но Rack сможет сделать вид, что получил PUT, а не POST.
Что было до API?
API существовал не всегда. Его появление на рынке стало технологической революцией и внесло много изменений в онлайн мир.
Однако, до этого момента паблишеры просто агрегировали множество различных параграфов определенного содержания и несколько изображений партнерских программ, что представляло собой мерч рекламодателя.
В чем была проблема?
Этот контент мог бы быть идеальным, но сопровождался риском стать устаревшим и содержать недействительные ссылки.
Если бы контент содержал старые ссылки, невозможно было бы обновлять информацию без необходимости просмотра всего сайта вручную и изменения конкретной информации.
С API процесс стал проще, так как API может синхронизировать информацию между программными приложениями.
Как API используются в контексте всемирной паутины?
Во всемирной паутине API позволяют вам легко получить доступ одновременно к нескольким ресурсам, которые доступны только на стороне другого программного приложения, на другом сервере.
Пример того, как используется API:
Знаете, почему вы можете быстро зарегистрироваться в разных приложениях, используя только аккаунт Facebook?
Это происходит благодаря специальному API Facebook. Компании используют код и API для предоставления клиентам быстрого и простого доступа к их платформам.
Что будет, если не использовать API?
Если вы решите не использовать API, приложение может, например, узнать о новой статье Академии Mobidea открыв www.academy.mobidea.com
Затем приложение прочтет веб страницу, как если бы оно было человеком, и интерпретирует контент страницы, в данном случае – Академии.
Та же ситуация с использованием API: приложение находит информацию о веб странице www.academy.mobidea.com , отправив сообщение на API Академии Mobidea.
Сообщение отправляется в формате JSON.
Что такое формат JSON?
Формат JSON (JavaScript Object Notation) это файл открытого стандарта, содержащий объекты данных и соответствующие атрибуты.
Например, когда мы проверяем новые статьи в Академии Mobidea, передаваемый JSON файл выглядел бы так:
article {
title: “Новая статья”,
date: 01/01/2017,
content: “Много текста.”,
author: “Джон Уайт”
}
Далее, после отправки сообщения в формате JSON, API страницы www.academy.mobidea.com реагирует структурированным ответом, похожим на пример выше.
Почему метод передачи информации так важен?
Вот почему: когда вы используете API, веб страница документирует определенную структуру ответа и запроса.
Это значит, что информация остается неизменной, вне зависимости от того, меняет ли веб страница свой внешний вид и дизайн или нет.
Без API приложение определенно должно полагаться на неточный факт, что вебсайт не изменит свой внешний вид.
Что случится, если сайт поменяется, и при этом API не был использован?
Скорее всего приложение перестанет работать!
В силу изменения структуры, дизайна и пользовательского опыта сайта приложение перестанет его распознавать.
Оно просто не сможет понять данные, передаваемые с данного вебсайта.
Advertisement
В итоге, API это более безопасный и надежный вариант.
С ним вы можете быть уверены в том, что приложение продолжит работать с сайтом.
Не имеет значения, если сайт вдруг решил изменить дизайн или структуру – API прочтет его в любом случае.
Почему дизайн API так важен
Хороший дизайн API имеет решающее значение для успешного использования API, и архитекторы программного обеспечения тратят много времени на изучение всех возможных приложений API и наиболее логичного способа его использования.
Структуры данных и значения параметров имеют особое значение, поскольку они должны совпадать между вызывающим API и его издателем.
Безопасность – важный аспект разработки API. Использование неверно настроенных API-интерфейсов – обычная практика для кибер-злоумышленников. API-интерфейсы – это шлюз, который представляет системы и данные организации внутренним и внешним пользователям – любой взлом может создать серьезные проблемы безопасности.
Пример Twitter API
Пример. У твиттера есть сайт, на котором мы можем просматривать твиты. Кликая по ссылкам мы попадаем на разные адреса, по которым доступна разная информация: лента твитов, страница твита, личный кабинет, сброс пароля, рекламный кабинет и так далее.
- https://twitter.com/mokevnin – страница конкретного пользователя
- https://twitter.com/mokevnin/status/1446464250499710976 – страница конкретного твита
Каждая из этих страниц возвращает HTML, в котором информация представлена в том виде, в котором мы ее видим, со всеми элементами дизайна. Сайт твиттера адаптирован под небольшие экраны, поэтому открывается с любого устройства где есть браузер. Но кроме сайта у твиттера есть и мобильное приложение, которое показывает ту же самую информацию, но с другим, более удобным интерфейсом, адаптированным под конкретный телефон.
Мобильное приложение, в отличии от сайта, физически хранится и запускается прямо на телефоне. И весь внешний вид тоже описывается внутри приложения. Для работы такого приложения нужны чистые данные, которых на телефоне нет, они есть на серверах твиттера. Как загрузить их на телефон? Обычные адрес страниц нам не подходят, так как они возвращают не данные, а готовые html-страницы.
Именно здесь на помощь приходит API. Твиттер предоставляет специальные http-адреса, по которым доступны чистые данные, а не конкретные интернет-страницы с готовым внешним видом. Данные по таким адресам отдаются в структурированном формате, чаще всего JSON. Один сервис “упаковывает” данные в JSON формат, другой, который ходит за данными, “распаковывает” их из JSON и использует внутри себя для отображения. Пример запроса пользователя:
Задача этого API дать удобный доступ к данным твиттера. Причем это API используется как самим твиттером в мобильных приложениях, так и сторонними сервисами, которые управляют твиттером. Например маркетологи используют сервисы, которые автоматически публикуют твиты по расписанию.
Кстати, сам твиттер использует свое API, в том числе для виджетов, которые можно встраивать на любой сайт для отображения конкретного твита или ленты твитов, хороший пример – главная Хекслета. И, если говорить откровенно, то сам сайт твиттера работает по API. В браузер грузится JS-код, который реализует логику вывода и ходит за данными на сервер (по API).
У твиттера есть специальный сайт для разработчиков, на котором подробно описано их API, адреса, параметры, которые можно передавать и форматы ответов. Подобное описание есть у любого сервиса с публичным API, то есть доступным для использования в интернете. Правда публичное не означает бесплатное, API может быть и часто бывает платным.
Кратко о различных шаблонах API
Существует несколько шаблонов для разработки API. Эти шаблоны имеют свою историю, разные требования и создают разные возможности для пользователей. Эти конструкции так или иначе связаны друг с другом, поэтому мы увидим много мест, где они очень похожи. Понимание их поможет вам принять решение о том, какие из них использовать для решения ваших конкретных задач.
Стиль туннелирования
Туннелирование работает как система удаленных вызовов процедур (RPC), организованных в формате сообщений XML. RPC сам по себе является действительно старой технологией, которая лучше всего подходит для передачи команд и процедур. SOAP в некоторых случаях использует туннелирование.
SOAP – Простой протокол доступа к объектам
Можно утверждать, что SOAP является протоколом связи, а не архитектурой/шаблоном API, потому что он определяет свой набор правил связи и протоколов безопасности и все такое. SOAP API-интерфейсы более затратны, чем их аналоги, но также имеют и свои преимущества. Они обеспечивают большую безопасность при разработке крупномасштабных корпоративных приложений.
Выбор SOAP основывается на функциях, связанных с безопасностью, транзакциями и соответствием набору ACID (атомарность, согласованность, изолированность, долговечность), что делает его более привлекательным для приложений корпоративного масштаба.
REST
REST – это действительно API-интерфейс «веб-сервисов», помещающий его на противоположную сторону SOAP. REST API основаны на URI (унифицированный идентификатор ресурса) и протоколе HTTP. REST API могут обмениваться данными в формате JSON или XML, хотя многие API REST отправляют данные в виде JSON.
При создании системы с минимальными соображениями безопасности, но с высокими требованиями к скорости, REST является отличным выбором. REST API-интерфейсы имеют меньше требований к безопасности, улучшают совместимость с клиентом браузера, открываемость, работоспособность данных и масштабируемость – вещи, которые действительно применимы к веб-сервисам.
API-документация
Настройка взаимодействия между двумя сервисами — это своеобразный договор, в котором прописаны условия сотрудничества. В API-документации каждого сервиса указаны условия, на которых сторонние сайты или приложения могут использовать его функционал. Например, та же социальная сеть ВКонтакте предоставляет разработчикам возможность использовать id пользователей, видеозаписи, документы, карточки товаров на сторонних сервисах.
Для корректной работы с API в документации прописывают конкретные операции и методы, с помощью которых можно их выполнить:
- video.add — метод для добавления видео из плеера ВКонтакте;
- likes.delete — метод для удаления отметки «Нравится»;
- users.get — метод для получения информации о пользователе.
Методы поделены на группы в соответствии с разделом контента: photos, videos, docs, likes и другие. Полный список методов можно найти на специальной странице API-документации ВКонтакте.
По условиям документации, чтобы выполнить каждое действие с помощью методов, нужно оформить запрос по определенным правилам. Например, для ВКонтакте нужно указать:
https:// — протокол соединения, он всегда будет один и тот же;
api.vk.com/method — адрес API-сервиса; в зависимости от сервиса он будет меняться, но у ВКонтакте адрес API выглядит именно так;
users.get — название конкретного метода API ВКонтакте;
user_id=210700286 — id конкретного пользователя, данные о котором необходимо получить.
https://api.vk.com/method/users.get?user_id=210700286&v=5.52
В ответ на запрос сервер возвращает JSON-объект с запрошенными данными, он будет выглядеть так:
{«response»:}
Если разложить ответ на составляющие, то:
- в поле id будет все тот же идентификационный номер аккаунта;
- в поле first_name — строка с именем пользователя;
- в поле last_name — строка с фамилией пользователя.
Метод получения информации о пользователе используют, например, сайты с возможностью авторизации через аккаунт ВКонтакте. Так сайт может привязать окошко своего сообщества в этой соцсети, показать пользователю, кто из друзей в нем уже состоит, предложить поделиться страницей в профиле или поставить «Нравится» прямо на странице сайта.
Второй аспект
Если вы владелец сложных вычислительных мощностей, популярного сервиса или хранилища данных для открытого или полуприватного доступа, то хорошим ходом будет поднять собственное API. Что это даст:
- Большой поток клиентов.
- Упрощенный доступ к вашим услугам для партнеров.
- Удобство статистического анализа использования сервиса.
Третий аспект
Почти тот же, что и второй. Но без необходимости реализовывать API для открытого доступа. Если у вас есть портал, и вы хотите создать под него мобильное приложение на Android/IOS, то переписать систему под единое API – лучшее решение. Вся структура данных систематизируется. Сайт и приложение будут работать через единые каналы данных.
