Soap api что это
Как использовать REST и SOAP API в Zimbra OSE
Как и практически любой современный веб-сервис, Zimbra OSE имеет интерфейсы обмена данных, которые позволяют получать доступ к различным функциям сервера и хранящимся на нем данным. API используются для разработки различных приложений и для интеграции Zimbra с другими корпоративными системами. Zimbra OSE поддерживает REST API и SOAP API. В данной статье мы разберем отличия, сферы применения и примеры использования SOAP и REST API в Zimbra OSE.
SOAP и REST API — в чем различия?
Несмотря на то, что SOAP API и REST API фактически выполняют одну и ту же функцию, различий между ними больше, чем сходств, и начинаются эти различия с определения. Так, если SOAP — это протокол, который призван стандартизировать обмен данными между веб-сервисами, независимо от того, на каком языке они написаны, то REST — это архитектурный стиль веб-сервиса, подразумевающий ряд ограничений, в соответствии с которым создается веб-сервис.
Конкретно в Zimbra REST API и SOAP API различаются сферами применения. REST API здесь используется только для CRUD-операций, то есть для создания, чтения, обновления и удаления объектов на сервере. Поэтому используется REST API в основном для создания простых интеграций со сторонними системами, так как он позволяет выгружать из Zimbra данные в различных форматах, таких как xml, json, rss, html, zip, tar, tgz, ics, ifb, csv и других, а также импортировать данные в Zimbra. SOAP API помимо управления данными почтовых ящиков может быть использован для других операций. Существенным отличием также является то, что REST менее безопасен чем SOAP.
От командной строки, которая в Zimbra OSE обладает даже большей функциональностью и поддерживает формирование bash-скриптов, API отличается тем, что для их работы не требуется доступ к системной учетной записи Zimbra на почтовом сервере.
REST API представлен в Zimbra OSE набором методов для работы с почтой, календарями, задачами и контактами. Среди них:
Результатом этой команды будет создание файла token.txt в домашней папке пользователя, который будет содержать токен аутентификации. Обращаем ваше внимание на то, что данный токен имеет ограниченный срок годности и по истечении этого срока потребуется выпустить новый токен для доступа к почтовому ящику Zimbra по REST-запросам. Сам токен представляет из себя строку длиной 313 символов, начинающуюся с ‘0_’.
/inbox xml, где 0_xxx — это токен аутентификации, auth=qp — это метод аутентификации по токену, fmt=rss — формат вывода данных, а
/inbox xml — это файл, в который будет экспортировано содержимое папки «Входящие».
Добавляя различные аргументы к REST-запросу можно частично экспортировать данные из папки «Входящие». Например:
/contacts.csv ‘https://example.ru:7070/home/user@example.ru/contacts?fmt=csv&auth=qp&zauthtoken=0_xxx можно импортировать CSV-файл с контактами.
SOAP API значительно сложнее в работе, чем REST API, но при этом имеет гораздо больше возможностей. Помимо управления данными, хранящимися на сервере, SOAP API позволяет управлять учетными записями, доменами, фактически предоставляя доступ ко всей функциональности Zimbra. Именно поэтому SOAP API используется для написания более сложных клиентских приложений. Например для изменения настроек учетной записи и поэтому используется для создания более продвинутых приложений. Например, веб-клиент Zimbra OSE обменивается информацией с сервером, используя SOAP API.
Как уже говорилось выше, SOAP представляет из себя протокол обмена жестко структурированными xml-сообщениями, в которых одно приложение может передавать данные другому. Транспортом для передачи SOAP-сообщений обычно является HTTP.
SOAP API в Zimbra OSE разбито на несколько составляющих частей. Среди них:
Для выполнения большинства SOAP-запросов необходимо пройти аутентификацию. Для этого существуют SOAP-методы Auth в zimbraAdmin и zimbraAccount. Пример SOAP-запроса для аутентификации будет выглядеть следующим образом
В данном примере user@example.ru — это имя пользователя, а qwerty123 — его пароль. Также в адресной строке запроса не забудьте указать в качестве способа соединения https, так как иначе можно столкнуться с разрывом соединения со стороны Zimbra. Ответ от сервера будет выглядеть следующим образом:
Для примера создадим запрос на отправку электронного письма в Zimbra OSE. Пример соответствующего SOAP-запроса будет выглядеть так:
Здесь в поле authToken необходимо указать полученный ранее токен аутентификации, в поле SendMsgRequest указать тему и текст письма, а также учетные записи и имена отправителя и получателя.
В данном случае мы вручную составили несколько SOAP- и REST-запросов для Zimbra. Однако и их формирование можно автоматизировать за счет создания скриптов на различных языках программирования. Об этом в одной из наших следующих статей.
Дао Вебсервиса. (Или да хватит же изобретать велосипеды!)
Недавно на Хабре была опубликована статья под провокационным заголовком и призывом к прекращению изобретений велосипедов в API-строении. Поскольку тема мне интересна, то я просто не мог пройти мимо.
Увы, реальность за хабракатом меня сильно разочаровала — я увидел очередной велосипед, да еще и с квадратными колесами. (Коллеги, ничего личного, только техническое обсуждение.) Правда, авторы честно сказали, что увидели на нескольких сайтах модное слово REST и решили сделать по нему. Только вот поняли они этот «РЭСТ» по-своему, примерно как Дед Щукарь читал и понимал толковый словарь.
В этом топике я призываю по-настоящему покончить с велосипедами в API сайтов. Ведь получается какой анекдот: АПИ разрабатывается для упрощения доступа к сайту и легкости подключения внешних систем, а получается такой, что с ним еще сложнее, чем без него 🙂
Чуть ниже под катом я подпишу смертный приговор всем велосипедам в универсальных API. Чтобы не быть голословным, я все проиллюстрирую примерами.
Но должен предупредить сразу — после прочтения статьи вы не сможете без рвотного рефлекса смотреть на очередной велосипед Васи Пупкина под гордым названием «универсальное API сайта».
Итак на сегодня наиболее распространенными способами доступа к API сайтов являются:
1. XML-RPC.
2. REST (с оговоркой, что это не протокол, а подход).
3. SOAP.
Базовые технологии и сравнение
XML-RPC
Примерно так же просто выглядят сообщения об ошибках. Такой ответ легко распарсить даже человеку, не говоря уже про машину. Такая простота сослужила ему двоякую службу: с одной стороны он не был принят заказчиком и не стал стандартом, а с другой — понравился толпе простых незамороченных программистов. Этим ребятам нужно было простое и надежное средство обмена информацией между системами, они не хотели заморачиваться на такую хрень как красивый УРЛ, схема документа и прочие академизмы. Первое, что они хотели получить — простую работающую систему. И до сих пор XML-RPC помогает им в этом.
Итак:
+ : простота, краткость сообщений, минимальная проверка формата данных,
— : недостаточная строгость, требуется отдельное описание сервиса.
POST /api/object.php?object_id=445&action=delete&user_id=255&auth_key=0Jf4tet5 HTTP/1.1
При этом, если XML-RPC использует из HTTP-протокола только транспортную часть для передачи XML-ки запроса/ответа, то REST задействует HTTP по-полной: здесь и авторизационные заголовки, content-negotiation — предпочтения по формату, языку, кодировке и виду ответа, различные служебные заголовки, безгеморная передача бинарных данных и т.п. Ошибки хорошо описываются кодами HTTP 4xx и 5xx. Можно видеть, что REST — органичная надстройка над HTTP. Это неудивительно ведь Рой — один из разработчиков протокола HTTP. Вообще, чем больше я разбираюсь с этим протоколом тем больше мне кажется, что он опередил свое время лет на 20, и чем дальше развивается веб, тем больше возможностей мы из него используем.
Само тело сообщения может передаваться в разных форматах: классическом XML либо гиковском JSON. Вообще, REST это не протокол, это подход, и как раз здесь заключена его гибкость, он как бы говорит нам: «Ребята, берите базовые принципы, а дальше делайте как вам удобно». Близость к HTTP-протоколу упрощает и ускоряет его обработку веб-серверами.
Итак:
+ : гибкость, простота, скорость обработки (особенно важно для крупных сайтов), органичность протоколу, мультиформатность, компактность.
— : отсутствие строго контроля данных, из практических соображений приходится выходить за рамки идеальной модели.
— Фак май мозг! — воскликнете вы и будете абсолютно правы — Это что же, ради передачи фитюльки на 10 байт мне надо всю эту лабуду писать?
— Да — скажет Логика, и вы, засучив рукава пойдете учить всю эту кучу технологий.
— Сюда еще и XML Schema приплели зачем-то? Какого хрена? А вы уверены, что эти ребята правильно понимают смысл слова «Simple»? — такие мысли будут вас посещать, и это хорошо — вы на верном пути.
Но и это не все: чем больше копаешься в SOAP тем больше всяких разных технологий вылазит на тебя. Когда вы дойдете до WSDL (Язык описания веб-сервисов), вы поймете почему, начиная с какой-то версии, разработчики перестали воспринимать название SOAP как аббревиатуру, а начали понимать буквально — soap («мыло»). В этот момент ваши мысли будет занимать одна идея: почему во всем этом зоопарке технологий отсутствует технология rope («веревка»).
Еще через какое-то время вы воскликните: «Ну нафиг, давайте уж без меня: сами придумали — сами и возитесь. Я вам не машина мегабайты иксэмеля в мозгу парсить!».
Поздравляю: теперь вы постигли дао вебсервисов!
Да! Дао веб-сервиса именно в этом и состоит: это язык общения машин и человеку нафиг не надо туда лезть. Надо просто его использовать. Ведь когда вам нужна какая-то программа, вы ее запускаете, а не лезете в бинарный код, чтобы исполнять его в мозгу. Точно так же вы не отправляете HTTP-запросы руками в командной строке, а используете браузер. Так зачем здесь лезть в эту гопу голыми руками, да еще хвастаться кто залез по локоть, а кто по самое плечо? Надо просто его использовать.
Просветленные API
API сайта и веб-сервисы — это не что-то милостиво спущенное на нас с небес создателями сайта! Это банальная библиотека функций, которую мы можем встроить в свою программу. Этот вывод становится совершенно естественным, когда вы начинаете мыслить глобально за пределами своего компьютера.
Если вам нужна новая уже готовая либа в проекте, что вы делаете? Скорее всего просто скачиваете, устанавливаете и используете? Пишете в начале программы use/require/import/include/… а дальше просто вызываете функции. Почему же работа с веб-библиотекой должна быть сложнее?
Вот теперь, просветлившись, мы можем начать работать с просветленным API.
Сейчас в качестве примера мы 1 минуту сделаем работу с API Аэрофлота, будем подглядывать за табло Шереметьево без отрыва задницы от стула. Я беру свой любимый язык и на нем пишу все примеры. Уверен, в вашем языке есть аналогичные модули. Ну а если их там нет, то самое время задуматься, так ли взаимна ваша любовь 😉
Вот тут аэрофлот подробно расписывает свое чудесное API. На первый взгляд, описание достаточно убогое — чисто перечисление методов и параметров. А как же это вызывать, как парсить, что вообще делать? А это уже не наши заботы — пусть об этом болит голова у машины — она же железная, а свою мне не хочется грузить фуфлом. Поэтому моя задача найти машинночитаемое описание сервиса — тот самый WSDL и скормить его компу.
Стойте-стойте, а как же вся эта лабуда с XML, REST, передачей параметров, парсингом ответов и всеми прочими атрибутами «крутого» API?
Лучше всего на это отвечает фильм «Матрица», кадр из которого мне захотелось вынести в заголовок:
Только перестав думать о ложке сайтовом API как о чем-то реальном, сложном, можно начать гнуть ее комфортно использовать.
Это и есть просветленное API — прозрачное и светлое настолько, что вы его не замечаете, когда работаете. Для вас это просто локальная библиотека. А вся остальная механика с сетевыми заморочками происходит где-то внутри и вас не напрягает.
Как отличить сайтовое API от говна.
Полагаю, внимательный читатель уже догадался?
Когда вместо простой, прозрачной и удобной работы с API сайта вам приходится морочиться с тем, как бы отправить запрос этому сайту и почему он не хочет принимать так старательно сформированный с помощью curl-а запрос, то вывод должен быть однозначным. Вам подсунули неправильный шоколад.
Выводы
В наше время наличие API для сайта претендующего на внимание программистов, всевозможные интеграции и прочее — не повод для гордости, а предмет первой необходимости. Но мало сделать API, даже если вы используете самые модные принципы — надо его сделать удобным и прозрачным. И технология передачи данных здесь имеет значение 10-й важности — это вообще не нужно прикладному программисту. Он должен просто взять и использовать вашу библиотеку.
Если вы хотите получить его внимание, чтобы он потратил свое время на интеграцию с вами — сделайте первый шаг — потратьте время на него. Дайте ему очень простую и понятную библиотеку.
Не надо кивать на то, что «мы сделали как твиттер — дали REST-подобный интерфейс». Вы забываете главное — у твиттера на каждый язык программирования по 5-10 библиотек, которые можно просто скачать и использовать не заморачиваясь на протокол rest/xmlrpc/soap.
Сравнение архитектурных стилей API: SOAP vs REST vs GraphQL vs RPC
Feb 4 · 12 min read
Два отдельных приложения нуждаются в посреднике, чтобы общаться друг с другом. Поэтому разработчики часто строят мосты — программные интерфейсы приложений, они же API, — чтобы предоставить одной системе доступ к информации или функциональности из другой.
Чтобы способствовать быстрой и масштабной интеграции приложений, API реализуются с использованием протоколов и/или спецификаций, определяющих семантику и синтаксис передаваемых сообщений. Эти спецификации составляют архитектуру API.
Со временем появились различные архитектурные стили API. Каждый из них содержит собственные схемы стандартизации обмена данными. Наличие выбора вызывает бесконечные споры о том, какой архитектурный стиль лучше.
Сегодня многи е пользователи API называют REST “Rest in peace” (“Покойся с миром”) и болеют за успех GraphQL, в то время как десять лет назад ситуация была обратной: REST как победитель, пришедший на замену SOAP. Проблема с этими мнениями в том, что они однобоко поднимают на щит какую-то технологию вместо того, чтобы рассматривать ее фактические свойства и характеристики относительно конкретной ситуации.
В этой статье мы останемся объективными и обсудим четыре основных стиля API в порядке их появления, сравним их сильные и слабые стороны и выделим сценарии, для которых каждый из них подходит лучше всего.
Удаленный вызов процедуры (RPC): вызов функции в другой системе
Удаленный вызов процедуры ( Remote Procedure Call) — это спецификация, которая позволяет удаленно выполнять функцию в другом контексте. RPC расширяет понятие локального вызова процедуры, но помещает его в контекст HTTP API.
Проблематичность первоначального XML-RPC связана со сложностями в обеспечении типов данных для полезных нагрузок XML. Позже API RPC задействовал более конкретную спецификацию JSON-RPC, которая считается более простой альтернативой SOAP. gRPC — последняя версия RPC, разработанная компанией Google в 2015 году. Благодаря подключаемым поддержке балансировки нагрузки, трассировки, проверки работоспособности и аутентификации gRPC хорошо подходит для микросервисов.
Как работает RPC
Клиент вызывает удаленную процедуру, сериализует параметры и дополнительную информацию в сообщении и отправляет это сообщение на сервер. Получив сообщение, сервер десериализует его содержимое, выполняет запрошенную операцию и отправляет результат обратно клиенту. Стаб сервера и стаб клиента берут на себя сериализацию и десериализацию параметров.
Преимущества RPC
Простота и понятность взаимодействий. RPC использует GET для получения информации и POST для всего остального. Механика взаимодействия между сервером и клиентом сводится к вызову конечной точки и получению ответа.
Легкость добавления функций. Получив новое требование для API, мы можем легко добавить другую конечную точку, выполняющую это требование: 1) написать новую функцию и перебросить ее на конечную точку, и 2) теперь клиент может попасть в эту конечную точку и получить информацию, соответствующую заданному требованию.
Высокая производительность. Легкие полезные нагрузки легко распределяются по сети, обеспечивая высокую производительность, что важно для общих серверов и параллельных вычислений, выполняемых в сетях рабочих станций. RPC способен оптимизировать сетевой уровень и сделать его очень эффективным в ситуации, когда различные сервисы каждый день обмениваются тоннами сообщений.
Недостатки RPC
Плотная связь с базовой системой. Уровень абстракции API способствует его повторному использованию. Чем теснее связанность с базовой системой, тем хуже API подходит для других систем. Тесная связь RPC с базовой системой не позволяет создать уровень абстракции между функциями в системе и внешним API. Отсюда вытекают вопросы относительно безопасности, поскольку детали реализации базовой системы довольно легко просачиваются в API. Плотная связанность RPC создает трудности для требований к масштабируемости и слабо связанных команды. Таким образом, клиент либо беспокоится о возможных побочных эффектах вызова определенной конечной точки, либо пытается выяснить, какую конечную точку следует вызвать, потому что не понимает, по какому принципу сервер именует функции.
Низкая обнаруживаемость. В RPC нет никакого способа интроспектировать API или отправить запрос и начать понимать, какую функцию вызывать на основе его запросов.
Взрыв функций. Новые функции создавать очень легко. Поэтому вместо того, чтобы редактировать существующие, мы создаем новые, в результате чего получаем огромный список перекрывающихся функций, которые трудно понять.
Примеры использования RPC
Шаблон RPC получил первое применение примерно в 80-х годах, но это само по себе не делает его устаревшим. Крупные компании, такие как Google, Facebook (Apache Thrift) и Twitch (Twirp), используют внутри себя высокопроизводительные вариации RPC для чрезвычайно высокопроизводительного обмена сообщениями с низкими накладными расходами. Их массивные системы микросервисов требуют, чтобы внутренняя коммуникация была четкой и в то же время организованной в короткие сообщения.
API для команд. RPC — подходящий выбор для отправки команд в удаленную систему. Например, Slack API очень командно-ориентирован: зайти на канал, покинуть канал, отправить сообщение. Разработчики Slack API как раз и смоделировали его в стиле RPC, сделав его маленьким, компактным и простым в использовании.
Клиентские API для внутренних микросервисов. В случае прямой интеграции между единственным поставщиком и потребителем не хочется тратить много времени на передачу большого количества метаданных, как это делает REST API. gRPC и Twirp очень подходят для микросервисов благодаря высокой скорости передачи сообщений и их производительности. gRPC, с HTTP2 под капотом, способен оптимизировать сетевой уровень и повысить его эффективность при отправке с одного сервиса на другой тонн сообщений в день. Однако, если вы стремитесь не к высокой производительности сети, а к стабильному API-контакту между командами, публикующими очень отличающиеся друг от друга микросервисы, REST позаботится об этом лучше.
Протокол доступа к простым объектам (SOAP): предоставление данных в виде сервисов
SOAP — это высоко-стандартизированный протокол веб-коммуникаций, основанный на формате XML. Выпущенный Microsoft через год после XML-RPC, SOAP многое от него унаследовал. Когда на сцену вышел REST, они сначала применялись параллельно, но вскоре REST выиграл конкурс популярности.
Как работает SOAP
Формат XML тянет за собой много формальностей. В сочетании с массивной структурой сообщений он делает SOAP самым подробным стилем API.
SOAP-сообщение состоит из:
Логика SOAP API написана на языке описания веб-служб (WSDL). Этот язык описания API определяет конечные точки и описывает все процессы, которые могут быть выполнены. Это позволяет различным языкам программирования и IDE быстро налаживать коммуникацию.
SOAP поддерживает обмен сообщениями с отслеживанием состояния и без такового. В сценарии с отслеживанием состояния сервер хранит полученную информацию, которая может весить очень много. Но это оправдано для многосторонних операций и сложных транзакций.
Плюсы SOAP
Независимость от языка и платформы. Встроенная функциональность для создания веб-сервисов позволяет SOAP обрабатывать сообщения и делать ответы независимыми от языка и платформы.
Связанность с различными транспортными протоколами. SOAP гибок с точки зрения протоколов передачи и приспосабливается к более чем одному сценарию.
Встроенная обработка ошибок. Спецификация SOAP API позволяет возвращать XML-сообщение Retry с кодом ошибки и ее объяснением.
Ряд расширений безопасности. Благодаря интеграции с протоколами WS-Security качество транзакций SOAP соответствует корпоративным стандартам. SOAP гарантирует конфиденциальность и целостность внутри транзакций, обеспечивая при этом шифрование на уровне сообщений.
Минусы SOAP
В наши дни многие разработчики содрогаются при мысли о необходимости интеграции SOAP API по нескольким причинам.
Только XML. SOAP-сообщения содержат много метаданных и поддерживают только подробные XML-структуры для запросов и ответов.
Тяжеловесность. Из-за большого размера XML-файлов SOAP-сервисы требуют большой пропускной способности.
Узкоспециализированные знания. Создание серверов SOAP API требует глубокого понимания всех задействованных протоколов и их строгих правил.
Утомительное обновление сообщений. Требуются дополнительные усилия для добавления или удаления свойств сообщения — жесткая схема SOAP замедляет принятие.
Сценарии применения SOAP
В настоящее время архитектура SOAP чаще всего применяется для интеграции внутри предприятий или с их доверенными партнерами.
Надежность передачи данных. Жесткая структура SOAP, а также возможности в плане безопасности и авторизации, делают его наиболее подходящим вариантом для обеспечения соответствия формальному программному контракту между API и клиентом при соблюдении юридического контракта между поставщиком API и потребителем API. Вот почему финансовые организации и другие корпоративные пользователи выбирают SOAP.
Передача состояния представления (REST): предоставление данных в качестве ресурсов
REST — самоописательный архитектурный стиль API, определяемый набором архитектурных ограничений и предназначенный для широкого внедрения многими потребителями API.
Наиболее распространенный сегодня стиль API был впервые описан в 2000 году Роем Филдингом в его докторской диссертации. REST делает доступными данные на стороне сервера, представляя их в простых форматах — чаще всего это JSON и XML.
Как работает REST
REST определен не так строго, как SOAP. RESTful-архитектура должна соответствовать шести архитектурным ограничениям:
На самом деле, некоторые сервисы соответствуют стандарту RESTful только в определенной степени. Они берут за основу стиль RPC, разбивают более крупные службы на ресурсы и эффективно используют инфраструктуру HTTP. Но ключевое здесь — гипермедиа, иначе HATEOAS, сокращенно от “Гипертекст как двигатель состояния приложения” (Hypertext As The Engine of Application State). По сути это означает, что с каждым ответом REST API предоставляет метаданные, связывающие всю информацию о применении API. Это то, что позволяет отделить клиента от сервера. В результате и поставщик API, и потребитель API могут развиваться независимо и это не затрудняет их коммуникацию.
“HATEOAS — ключевая особенность REST. Это действительно то, что делает REST самим собой. Поскольку большинство людей не используют HATEOAS, они пользуются HTTP RPC”, — такое радикальное мнение встретилось мне на Reddit. Действительно, HATEOAS — это самая зрелая версия REST. Однако этой цели трудно достичь. Для этого требуются гораздо более продвинутые и интеллектуальные клиенты API, чем те, которые обычно создаются и действуют в наши дни. Таким образом, даже действительно хорошие REST API сегодня не всегда соответствуют стандарту. Вот почему HATEOAS в основном служит ориентиром для долгосрочного развития дизайна RESTful API.
Между REST и RPC действительно может находиться серая зона, когда сервис реализует некоторые функции REST и некоторые RPC. REST основан на ресурсе (или существительном), а не на действии (или глаголе).
В REST все делается с помощью HTTP-методов, таких как GET, POST, PUT, DELETE, OPTIONS и, надеюсь, PATCH.