Что такое web service

Белый Виталий Владимирович

Факультет компьютерных наук и технологий

Кафедра прикладной математики и информатики

Специальность «Инженерия программного обеспечения»

Использование многоядерных процессоров для параллельного решения задачи Коши

Научный руководитель: к.т.н., доцент Назарова Ирина Акоповна

Ликбез по веб-сервисам

Что такое веб-сервисы?

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

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

Именно с появлением веб-сервисов развилась идея SOA — сервис-ориентированной архитектуры веб-приложений (Service Oriented Architecture).

Протоколы веб-сервисов

На сегодняшний день наибольшее распространение получили следующие протоколы реализации веб-сервисов:

На самом деле, SOAP произошел от XML-RPC и является следующей ступенью его развития. В то время как REST — это концепция, в основе которой лежит скорее архитектурный стиль, нежели новая технология, основанный на теории манипуляции объектами CRUD (Create Read Update Delete) в контексте концепций WWW.

Безусловно, существуют и иные протоколы, но, поскольку они не получили широкого распространения, мы остановимся в этом кратком обзоре на двух основных — SOAP и REST. XML-RPC ввиду того, что является несколько «устаревшим», мы рассматривать подробно не будем [1].

Классический подход (SOAP)

Веб-сервис идентифицируется строкой URI. Веб-сервис имеет программный интерфейс, представленный в машинно-обрабатываемом формате WSDL. Другие системы взаимодействуют с этим веб-сервисом путем обмена сообщениями протокола SOAP. В качестве транспорта для сообщений используется протокол HTTP. Описание веб-сервисов и их API могут быть найдены средствами UDDI. Концептуальная схема технологии приведена на рис. 1., а связь между протоколами — на рис. 2.

Рисунок 1 — Концепция веб-сервиса

Рисунок 2 — Протоколы веб-сервисов

Все спецификации, используемые в технологии, основаны на XML и, соответственно, наследуют его преимущества (структурированность, гибкость и т.д.) и недостатки (громоздкость, медлительность).

SOAP (изначально Simple Object Access Protocol, а в версии 1.2 официальная расшифровка аббревиатуры отсутствует) — простой протокол доступа к объектам (компонентам распределенной вычислительной системы), основанный на обмене структурированными сообщениями. Как любой текстовый протокол, SOAP может использоваться с любым протоколом прикладного уровня: SMTP, FTP, HTTPS и др., но чаще всего SOAP используется поверх HTTP.

Все сообщения SOAP оформляются в виде структуры, называемой конвертом (envelop), включающей следующие элементы:

Пример сообщения SOAP:

1 2001-06-22T14:00:00-05:00 Get up at 6:30 AM

Язык описания веб-сервисов (Web services Description Language, WSDL) предназначен для унифицированного представления внешних интерфейсов веб-службы. Текущая версия протокола WSDL 2.0 и она имеет некоторые отличия от предыдущих версий.

Таблица 1. Основные элементы протокола WSDL.

Рисунок 3 — Структура протокола WSDL

В спецификации WSDL 1.1 было определено 4 шаблона обмена сообщениями (типы операций):

В версии WSDL 2.0 эти шаблоны изменены и расширены в сторону поддержки сообщений об ошибках (например, шаблон Robust-in-only), но для обратной совместимости поддерживаются типы WSDL 1.1.

Universal Description, Discovery and Integration (UDDI, универсальный интерфейс распознавания, описания и интеграции) — открытый стандарт, утвержденный OASIS, определяющий методы публикации и обнаружения сетевых программных компонентов сервис-ориентированной архитектуры (SOA). В практической реализации UDDI представляет собой сетевой реестр (службу каталогов), представляющий данные и метаданные о веб-сервисах.

UDDI опирается на отраслевые стандарты HTTP, XML, XML Schema (XSD), SOAP и WSDL. Концептуальная связь между UDDI и другими протоколами стека веб-сервисов показана на рис. 4.

Рисунок 4 — Место UDDI в стеке протоколов веб-служб

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

Ключевыми функциями UDDI являются публикация информации о службе в реестре и поиск этой информации сторонними приложениями. Наряду с этими, реализованы и типовые для службы каталогов функции: представление модели хранимых данных и структуры информационной базы, отношения между объектами реестра, репликация, обеспечение безопасности и т.д. Все основные функции реестра представлены в виде веб-сервисов и доступны через API UDDI [2].

Архитектура REST

REST (Representational state transfer) — это стиль архитектуры программного обеспечения для распределенных систем, таких как World Wide Web, который, как правило, используется для построения веб-служб. Термин REST был введен в 2000 году Роем Филдингом, одним из авторов HTTP-протокола. Системы, поддерживающие REST, называются RESTful-системами.

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

А теперь тоже самое более наглядно:

Отсутствие дополнительных внутренних прослоек означает передачу данных в том же виде, что и сами данные. Т.е. мы не заворачиваем данные в XML, как это делает SOAP и XML-RPC, не используем AMF, как это делает Flash и т.д. Просто отдаем сами данные.

Каждая единица информации однозначно определяется URL — это значит, что URL по сути является первичным ключом для единицы данных. Т.е. например третья книга с книжной полки будет иметь вид /book/3, а 35 страница в этой книге — /book/3/page/35. Отсюда и получается строго заданный формат. Причем совершенно не имеет значения, в каком формате находятся данные по адресу /book/3/page/35 — это может быть и HTML, и отсканированная копия в виде jpeg-файла, и документ Microsoft Word.

Как происходит управление информацией сервиса — это целиком и полностью основывается на протоколе передачи данных. Наиболее распространенный протокол конечно же HTTP. Так вот, для HTTP действие над данными задается с помощью методов: GET (получить), PUT (добавить, заменить), POST (добавить, изменить, удалить), DELETE (удалить). Таким образом, действия CRUD (Create-Read-Updtae-Delete) могут выполняться как со всеми 4-мя методами, так и только с помощью GET и POST.

Вот как это будет выглядеть на примере:

ВАЖНОЕ ДОПОЛНЕНИЕ: Существуют так называемые REST-Patterns, которые различаются связыванием HTTP-методов с тем, что они делают. В частности, разные паттерны по-разному рассматривают POST и PUT. Однако, PUT предназначен для создания, реплейса или апдейта, для POST это не определено (The POST operation is very generic and no specific meaning can be attached to it). Поэтому данный пример будет правильным и в таком виде, и в виде если поменять местами POST и PUT.

Использование REST для построения Web-сервисов.

Как известно, web-сервис — это приложение работающее в World Wide Web и доступ к которому предоставляется по HTTP-протоколу, а обмен информации идет с помощью формата XML. Следовательно, формат данных передаваемых в теле запроса будет всегда XML.

Для каждой единицы информации (info) определяется 5 действий. А именно:

GET /info/ (Index) — получает список всех объектов. Как правило, это упрощенный список, т.е. содержащий только поля идентификатора и названия объекта, без остальных данных.

GET /info/ (View) — получает полную информацию о объекте.

PUT /info/ или POST /info/ (Create) — создает новый объект. Данные передаются в теле запроса без применения кодирования, даже urlencode.

POST /info/ или PUT /info/ (Edit) — изменяет данные с идентификатором , возможно заменяет их. Данные так же передаются в теле запроса, но в отличие от PUT здесь есть некоторый нюанс. Дело в том, что POST-запрос подразумевает наличие urldecoded-post-data. Т.е. если не применять кодирования — это нарушение стандарта. Тут кто как хочет – некоторые не обращают внимания на стандарт, некоторые используют какую-нибудь post-переменную.

DELETE /info/ (Delete) — удаляет данные с идентификатором .

Как видно, в архитектура REST очень проста в плане использования. По виду пришедшего запроса сразу можно определить, что он делает, не разбираясь в форматах (в отличие от SOAP, XML-RPC). Данные передаются без применения дополнительных слоев, поэтому REST считается менее ресурсоемким, поскольку не надо парсить запрос чтоб понять что он должен сделать и не надо переводить данные из одного формата в другой [3].

Немного кода

Далее представлен пример использования классического подхода построения веб-сервисов на основе JAX-WS.

Источник

Веб-сервисы в теории и на практике для начинающих

Что такое веб-сервисы?

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

Если посмотреть на веб-сервисы в разрезе стека сетевых протококолов, мы увидим, что это, в классическом случае, не что иное, как еще одна надстройка поверх протокола HTTP.

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

Но и сам Интернет — разнороден, т. е. различные приложения на различных узлах сети функционируют на разных аппаратно-программных платформах, и используют различные технологии и языки.

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

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

Именно с появлением веб-сервисов развилась идея SOA — сервис-ориентированной архитектуры веб-приложений (Service Oriented Architecture).

Протоколы веб-сервисов

На сегодняшний день наибольшее распространение получили следующие протоколы реализации веб-сервисов:

На самом деле, SOAP произошел от XML-RPC и является следующей ступенью его развития. В то время как REST — это концепция, в основе которой лежит скорее архитектурный стиль, нежели новая технология, основанный на теории манипуляции объектами CRUD (Create Read Update Delete) в контексте концепций WWW.

Безусловно, существуют и иные протоколы, но, поскольку они не получили широкого распространения, мы остановимся в этом кратком обзоре на двух основных — SOAP и REST. XML-RPC ввиду того, что является несколько «устаревшим», мы рассматривать подробно не будем.

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

SOAP против REST

Проблемы данного противостояния хорошо описаны в статье Леонида Черняка, найденой на портале www.citforum.ru.

По мнению же автора, кратко можно выделить следующее:

SOAP более применим в сложных архитектурах, где взаимодействие с объектами выходит за рамки теории CRUD, а вот в тех приложениях, которые не покидают рамки данной теории, вполне применимым может оказаться именно REST ввиду своей простоты и прозрачности. Действительно, если любым объектам вашего сервиса не нужны более сложные взаимоотношения, кроме: «Создать», «Прочитать», «Изменить», «Удалить» (как правило — в 99% случаев этого достаточно), возможно, именно REST станет правильным выбором. Кроме того, REST по сравнению с SOAP, может оказаться и более производительным, так как не требует затрат на разбор сложных XML команд на сервере (выполняются обычные HTTP запросы — PUT, GET, POST, DELETE). Хотя SOAP, в свою очередь, более надежен и безопасен.

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

Практическое применение веб-сервисов

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

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

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

Этап первый — реализация приложения сбора информации о курсах валют.

Информацию о курсах валют мы будем собирать со страниц сайта НБУ (Национального Банка Украины) ежедневно и складывать в базу данных под управлением СУБД MySQL.

Создадим структуру данных.

Таблица валют (currency):

Таблица номиналов обмена (exchange):

Для работы с базой данных воспользуемся ORM слоем на базе пакета PHP Doctrine. Реализуем граббер:

класс Grubber (models/Grabber.php):

и сам граббер (grabber.php):

Теперь заставим наш граббер отрабатывать раз в сутки в 10:00 утра, путем добавления команды запуска граббера в таблицы cron:

Все — у нас есть достаточно полезный сервис.

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

Реализация SOAP сервиса

Для реализации веб-сервиса на базе SOAP протокола, мы воспользуемся встроенным пакетом в PHP для работы с SOAP.

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

WSDL (Web Service Definition Language) — представляет из себя XML файл определенного формата. Подробное описание синтаксиса можно найти здесь.

На практике будет удобно воспользоваться функцией автоматической генерации файла, которую предоставляет IDE Zend Studio for Eclipse. Данная функция позволяет генерировать WSDL файл из классов PHP. Поэтому, прежде всего, мы должны написать класс, реализующий функциональность нашего сервиса.

класс CurrencyExchange (models/CurrencyExchange.php):

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

Не пишите в докблоках param void или return void — для WSDL это не критично, но вот при реализации REST доступа к тому-же классу у вас возникнут проблемы.

Теперь в Zend Studio входим в меню File->Export. выбираем PHP->WSDL, добавляем наш класс, прописываем URI-адрес нашего сервиса и создаем WSDL-файл. Результат должен быть примерно таким: http://mikhailstadnik.com/ctws/currency.wsdl

Если вы будете добавлять новую функциональность в ваш веб-сервис, вам нужно будет пересоздавать WSDL-файл. Но здесь не так все гладко. Следует учитывать, что SOAP-клиент, который уже запрашивал ваш WSDL файл, кеширует его на своей стороне. Поэтому, если вы замените старое содержимое новым в WSDL файле, некторые клиенты его не прочтут. А значит, при добавлении новой функциональности, дописывайте версию в имя вашего файла. И не забудбте обеспечить обратную совместимость для старых клиентов, особенно если вы не являетесь их поставщиком.

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

Реализация же самого сервера не предстваляет теперь никакой сложности:

Вы можете попробовать веб-сервис в работе по адресу: http://mikhailstadnik.com/ctws/
Там же доступен тестовый клиент: http://mikhailstadnik.com/ctws/client.php

Код простейшего клиента может быть таким:

Реализация REST сервиса

REST — это не стандарт и не спецификация, а архитектурный стиль, выстроенный на существующих, хорошо известных и контролируемых консорциумом W3C стандартах, таких, как HTTP, URI (Uniform Resource Identifier), XML и RDF (Resource Description Format). В REST-сервисах акцент сделан на доступ к ресурсам, а не на исполнение удаленных сервисов; в этом их кардинальное отличие от SOAP-сервисов.

И все же удаленный вызов процедур применим и в REST. Он использует методы PUT, GET, POST, DELETE HTTP протокола для манипуляции объектами. Кардинальное отличие его от SOAP в том, что REST остается HTTP-запросом.

Поскольку в PHP пока еще нет реалзации REST, мы воспользуемся Zend Framwork, в который включена реализация как REST клиента, так и REST севера.

Воспользуемся уже готовым классом CurrencyExchange. Напишем сам сервер:

Как видите все очень сходно и просто.

Однако, следует оговорить, что наш REST-сервис менее защищен, чем SOAP-сервис, так как любой добавленый метод в класс CurrencyExchange при его вызове отработает (сам класс определяет сруктуру сервиса).

Проверим работу нашего сервиса. Для этого достаточно передать параметры вызова метода в сроке GET-запроса:

При желании или необходимости вы можете самомтоятельно задавать структуру ваших XML ответов для сервиса REST. В этом случае, также будет необходимо позаботиться и о создании определения типа вашего XML документа (DTD — Document Type Definition). Это будет минимальным описанием API вашего сервиса.

Простейший тестовый клиент к REST сервису может быть в нашем случае таким:

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

Вы можете скачать пример в исходных кодах c PHP Doctrine и Zend Framework (4,42 Мб).

Заключение

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

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

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

Источник

WEB/HTTP сервисы. Базовые отличия и применение на практике

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

С точки зрения 1С, это два объекта метаданных, которые позволяют нам выполнять эти операции. Реализовывается доступ по классической трехзвенной схеме: это СУБД, в качестве сервера выступают кластер серверов 1С и веб-серверы, и клиент, подключающийся к сервису.

Зачем это нужно?

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

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

HTTP сервисы, поскольку они достаточно просты, могут выполняться на несложных и недорогих устройствах: таких как микрооборудование, телефония, терминалы сбора данных, электронные весы и так далее. Например, из 1С можно обратиться к IP-телефону, АТС или системе контроля доступа. В нашей практике был кейс, когда с телефонов Yealink вызывался сервис 1С, который записывал входящие звонки. Также это работало и в обратную сторону, и мы могли позвонить непосредственно с карточки клиента одним нажатием кнопки. Реализовывается это легко и быстро.

Благодаря HTTP сервисам мы можем использовать мощь технологий HTML, PHP, JavaScript для того, чтобы предоставлять интерфейс для конечных пользователей. Причем интерфейс может быть быстрым и легким, для него не потребуется загружать всю платформу. Нам необходимо будет сделать всего лишь страничку, которая будет передавать данные на сервис HTTP.

В нашей практике был случай, когда для заказчика нужно было сформировать внешнюю печатную форму на основании обязательной анкеты, которую заполняли клиенты на специальном планшете. Для этого для планшета была сделана веб-страничка. И пока клиенты ждали своей очереди, они заполняли эту страничку, проставляя галки в нужных местах. При нажатии на кнопку «Отправить» данные отправлялись на сервис 1С, где уже всей мощью платформы формировался документ PDF с печатью и подписью, который затем распечатывался и прикреплялся к данным клиента. Все это было сделано за полтора дня, без изменений типовой конфигурации, в расширении.

Такая страничка с двумя полями уже может передавать данные на внешний HTTP сервис:

Ниже скрин HTTP/WEB сервисов, которые используются у нас на текущем проекте. Обилие сервисов только подтверждает, что технология перспективная и очень интересная:

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

WEB и HTTP сервисы: сходства и различия

WEB и HTTP сервисы очень сходны между собой, но все же в них есть кардинальные отличия. Сходны они тем, что:

Теперь расскажем о различиях.

WEB технология — это сервисно-ориентированная технология, она по сути является удаленным вызовом процедур. Мы проектируем описание процедур, описание передаваемых параметров, и с помощью WEB сервисов мы эти процедуры можем вызывать. 1С со своей стороны также предоставляет технологию XDTO, которая позволяет валидировать входящие и исходящие данные, передаваемые в формате XML.

HTTP сервисы же основаны практически на голом HTTP, и эта технология ресурсно-ориентированная. Нет описания, нет проверки типов, нет проверки входящих и исходящих данных — есть только заголовки, параметры и тело запроса. И исторически используется формат данных JSON.

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

О форматах данных

Примерно так выглядит XML:

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

Именно поэтому его используют различного рода госорганы.

А так выглядит JSON — формат немного попроще:

Здесь есть основные типы данных: это объекты, формируемые фигурными скобками, массивы, формируемые квадратными скобками, и значение, которое формируется в виде текста.

Данные для HTTP-сервиса передаются в виде запроса HTTP, схематично изображенного ниже:

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

Так выглядит строка запроса в HTTP сервисе:

Сервис HTTP ресурсно-ориентирован. Конечные точки, к которым мы можем обращаться, являются ресурсами: они представлены именами существительными. На схеме это элементы строки orders и status, обозначающие соответственно ресурсы «Заказ» и «Статус заказа». Действия над ресурсами выполняются методами HTTP, базовыми из которых являются: get (получить ресурс), post (добавить ресурс), put (обновить ресурс), delete (удалить ресурс). Количество методов HTTP ограничено, действия над ресурсами тоже. Помимо указанных методов есть еще несколько дополнительных, но используются они значительно реже.

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

Про проектирование

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

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

Вспоминаем, что HTTP сервис — это у нас, в первую очередь, ресурсы. А ресурсы — это имена существительные: вот таких элементов, как /GetOrders или /orders/add, где в качестве ресурсов явно указываются глаголы действия, быть не должно. В качестве действий у нас должны выступать методы HTTP (get, post, delete).

Правильное проектирование обычно идет по иерархии: коллекция, элемент, ресурс. И вот здесь мы специально отобразили один интересный момент, связанный с особенностями ресурсной иерархии. Например, к заказу у нас прикрепляются накладные. Есть заказ, есть накладные, которые выдаются по этому заказу (одна или несколько). К этим накладным мы можем дать доступ и как к отдельному ресурсу /invoices, и как к ресурсу в составе заказа — когда накладная сделана на основе заказа /orders//attachedInvoices. Эти сущности идентичны, по обоим ресурсам можно получить одни и те же объекты, но именуются они по-разному, для отражения особенностей их получения. Это еще одна из рекомендаций протокола HTTP.

Для проектирования рекомендуется элементы, ресурсы и действия сводить в таблицу, где в строках располагаются ресурсы, а в столбцах — методы HTTP. На пересечениях строк и столбцов — описание, что должно выполняться в данном случае. Пример таблицы:

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

Про документацию

Если первый по важности пункт — это проектирование, второй — обязательно документация. HTTP протокол, HTTP сервисы не имеют описания, как это сделано в WEB сервисах. Поэтому документацию необходимо создавать, вести и обязательно поддерживать. Тем более, что ей пользуемся не только мы, но и партнеры.

В самом начале мы «забивали» на документацию, а когда партнеры спрашивали, каково предназначение того или иного метода, и что он в итоге принимает и возвращает — приходилось лезть в код. Теперь же мы просто говорим: посмотрите документацию, там все есть.

Документацию мы рекомендуем вести в таком виде:

Вот пример документации. Заголовок, ответ, пример, описание полей данных:

Будь мужиком! Пиши логи!

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

Разделяй код и властвуй над ним

Еще один очень важный момент при проектировании, при разработке таких систем — это разделение методов обработки самого HTTP запроса и методов обработки данных, которые являются методами бизнес-логики. Сначала мы делаем обработку самого HTTP запроса, расшифровываем заголовки, тело запроса и результаты передаем в процедуры обработки данных, в другой модуль — модуль бизнес-логики. Для формирование тела запроса и запроса партнеру имеет смысл использовать отдельные общие методы, включающие в себя автоматический вызов функций логирования. И, естественно, мы должны выполнять начальный контроль данных, потому что, в отличие от WEB сервисов, контроль данных у нас не производится.

На примере этого кода продемонстрировано использование указанных выше правил:

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

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

После подготовки данных вызывается модуль бизнес-логики, где происходит обработка данных. Результат обработки возвращается в виде структуры, после чего происходит формирование тела ответа.

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

Источник