Разработка REST API и библиотека RESTFormsЛебедюк Эдуард
InterSystems
2 | © InterSystems Corporation. All rights reserved. |
План
•Что такое REST
•Архитектура REST API
• Разработка
―Основы
―Отладка
―Тестирование и документирование
•Особенности―CORS
―Аутентификация
•RESTForms
Source: To add source, go to “Insert” tab, click on “Header & Footer”, check “Footer” and add the source information appropriate for the slide. (9pt)
Что такое REST
4 | © InterSystems Corporation. All rights reserved. |
REST
• Стиль архитектуры программного обеспечения для распределенных систем.
• Как правило используется для построения веб-служб.
• Любые данные однозначно определяется URL – это значит, что URL по сути является первичным ключом для единицы данных.
https://server:80/webapp/book/:bookid
5 | © InterSystems Corporation. All rights reserved. |
Принципы
• Разделение клиента и сервера
• Независимость от состояния (stateless)
• Кэшируемая и многоуровневая архитектура
• Единообразный интерфейс
• Все запросы к RESTful web API состоят из корневого URL
приложения плюс частные подзапросы
• CRUD (Create , Read, Update, Delete) через HTTP
6 | © InterSystems Corporation. All rights reserved. |
Преимущества
•Независимость от языка/фреймворка/платформы―Клиенты на Java, JS, .Net и т.д.
•Легкость разработки―Проще чем SOAP
•Легковесность
7 | © InterSystems Corporation. All rights reserved. |
Недостатки
• Привязан к протоколу HTTP
• Веб сервисы с более высокими требованиями сложно разрабатывать:
― Отсутствие стандартов обеспечения безопасности, политик, сообщений и т.д.
8 | © InterSystems Corporation. All rights reserved. |
JSON
{
"firstName": "John",
"lastName": "Smith",
"address": {
"streetAddress": "21 2nd Street",
"city": "New York",
"state": "NY",
"postalCode": 10021
},
"phoneNumbers": [ "212 555-1212", "646 555-4567“ ]
}
• JavaScript Object Notation
― Малый размер
― Человекочитаемость
― Быстрота генерации и обработки
• Поддержка начиная с 2009.2
• Расширенная поддержка в ядре начиная с 2016.1
9 | © InterSystems Corporation. All rights reserved. |
Взаимодействие
Ресурс GET PUT POST DELETE
Коллекция элементов
http://example.com/books
Получить список
URI элементов
коллекции,
возможно доп.
информацию.
Заменить
существующую
коллекцию на
новую.
Создать новый
элемент
коллекции.
Удалить
всю
коллекцию.
Один элемент коллекции
http://example.com/books/17
Получить всю
информацию об
элементе.
Обновить существующий
элемент.
Удалить
элемент
коллекции.
Корневая URL - http://example.com/
10 | © InterSystems Corporation. All rights reserved. |
Поддержка REST
• Полная поддержка начиная с 2014.2
• Улучшения, ускоряющие и упрощающие разработку выходят с каждым релизом
11 | © InterSystems Corporation. All rights reserved. |
Примеры REST API
MDX2JSON и клиент DeepSeeWeb
12 | © InterSystems Corporation. All rights reserved. |
Примеры REST API
Ensemble Workflow и клиент Ensemble Workflow UI
13 | © InterSystems Corporation. All rights reserved. |
RESTForms
•Проект для создания новых REST API с помощью обобщённого REST провайдера для хранимых классов
•Клиент на AngularJS
•Клиент на React
Архитектура REST API
15 | © InterSystems Corporation. All rights reserved. |
Архитектура REST API
Данные
Терминальное API
Web API
Клиент
16 | © InterSystems Corporation. All rights reserved. |
Терминальное API
• Взаимодействие с данными
• Данные не должны изменяться иначе, чем через это API
• Возвращают объекты или статус
• Не пишут на устройство
17 | © InterSystems Corporation. All rights reserved. |
Web API
• Преобразуют входящий запрос в форму, понимаемую терминальным API
• Вызывают методы терминального API
• Отправка результата выполнения терминального API клиенту
• Не взаимодействуют с данными напрямую
18 | © InterSystems Corporation. All rights reserved. |
Разделение API
• Терминальное API является основой логики приложения
• Функция Web API – преобразование запросов клиента в форму понятную терминальному API
и возврат клиенту результатов исполнения запроса
• Преимущества этого подхода:
― API выполняющие разные функции максимально разделены
― Возможна отладка вне веб-контекста
19 | © InterSystems Corporation. All rights reserved. |
Архитектура REST API
Данные
Терминальное API
Web API
Клиент
Разработка
21 | © InterSystems Corporation. All rights reserved. |
Брокеры
• Наследуются от %CSP.REST
• Содержит пути – сопоставления URI и вызываемых методов Caché
• Стандартный вид пути:
<Route
Url="/path/:param1/:param2"
Method="GET"
Call=“Package.Class:ClassMethod"
/>
• ClassMethod – любой метод класса Caché
22 | © InterSystems Corporation. All rights reserved. |
Разделение брокеров
%CSP.REST
Абстрактный брокер
Брокер 1
Брокер 2
Брокер 3
• «Физическое» разделение брокеров по классам
• Абстрактный брокер – преобразование запросов, CORS и т.п.
• Брокер 1..N – выполнение запросов
23 | © InterSystems Corporation. All rights reserved. |
Параметры брокера
Достаточно указать один раз в абстрактном брокере:
Parameter CONTENTTYPE = "application/json";
Parameter CHARSET = "UTF-8";
Parameter UseSession As BOOLEAN = 1;
24 | © InterSystems Corporation. All rights reserved. |
Логическая иерархия брокеров
Главный брокер
Брокер версии
Брокер предметной области 1
Брокер предметной области 2
Брокер предметной области 3
Брокеры могут «передавать» запросы друг другу
<Map Prefix="/form" Forward="Destination.Broker"/>
25 | © InterSystems Corporation. All rights reserved. |
Отладка
• REST клиент
• Перехватывающий прокси-сервер
• Анализатор трафика
Не надо:
• Использовать curl
• Использовать wget
• Использовать cli инструменты
26 | © InterSystems Corporation. All rights reserved. |
Тестирование и документирование
• Соединены с визуальными средствами отладки
• Внешние средства
― Swagger
― Postman
― …
Демо
https://www.youtube.com/watch?v=Q7xqqKEwv7U
Особенности
29 | © InterSystems Corporation. All rights reserved. |
CORS
• Cross-origin resource sharing (совместное использование ресурсов между разными
источниками) — технология современных браузеров, которая позволяет предоставить веб-
странице доступ к ресурсам другого домена.
• Parameter HandleCorsRequest = 1;
• ClassMethod OnHandleCorsRequest(pUrl As %String) As %Status {}
― Допустимый Origin – Host и IP сервера c клиентским веб-приложением
30 | © InterSystems Corporation. All rights reserved. |
Аутентификация
• Во всех брокерах Parameter UseSession = 1;
• Все веб приложения доступны только с аутентификацией
• У всех веб приложений установлен таймаут сессии (900, 3600)
• У всех приложений установлено одно значение GroupById
• У всех приложений установлено одно значение Cookie Path
RESTForms
32 | © InterSystems Corporation. All rights reserved. |
RESTForms
•Проект для создания новых REST API с помощью обобщённого REST провайдера для хранимых классов
•Работает начиная с 2016.1
•Цели проекта―Новые REST API без написания кода
―Минимальные изменения в хранимых классов
33 | © InterSystems Corporation. All rights reserved. |
Use cases
У вас уже есть данные в Caché и вы хотите предоставить часть данных (или все) в
виде REST API
Вам нужно создать REST API для нового приложения
34 | © InterSystems Corporation. All rights reserved. |
Архитектура приложения с использованием RESTForms
JS клиент RESTFormsДанные (классы)
35 | © InterSystems Corporation. All rights reserved. |
Возможности
•CRUD над объектом
•R над коллекциями (через SQL)
•Работа с файлами
•CRUD над классом
36 | © InterSystems Corporation. All rights reserved. |
Возможности
Метод URL Описание
GET form/info Список классов
GET form/info/all Метаинформация всех классов
GET form/info/:class Метаинформация одного класса
GET form/object/:class/:id Получить объект
GET form/object/:class/:id/:property Получить свойство объекта
POST form/object/:class Создать объект
PUT form/object/:class/:id Обновить объект из динамического объекта
PUT form/object/:class Обновить объект из объекта класса
DELETE form/object/:class/:id Удалить объект
GET form/objects/:class/:query Выполнить SQL запрос
37 | © InterSystems Corporation. All rights reserved. |
Особенности
•JS работает сразу
•Документация
•Примеры
•СПО, доступно на GitHub
38 | © InterSystems Corporation. All rights reserved. |
RESTFormsUI
• Просмотр данных RESTForms
• Поддержка мобильных устройств
• Адаптивный дизайн
• Клиент на AnglularJS
• Клиент на React
Демо RESTForms + RESTFormsUI
40 | © InterSystems Corporation. All rights reserved. |
RESTForms
• RESTForms упрощает создание нового REST API
• Пример организации REST API в части работы с данными и метаданными
• RESTForms – проверенная технология
― Ряд проектов с клиентами на AngularJS и React
― Примеры клиентов на GitHub
• RESTFormsUI позволяет сразу посмотреть на данные, предоставляемые RESTForms
Выводы
42 | © InterSystems Corporation. All rights reserved. |
Выводы
• REST на сегодня – основная и общепринятая методика построения API для сети интернет
• Предоставляя REST API вы получаете возможность выбора из огромного набора технологий
построения приложений-клиентов:
― JavaScript (AngularJS, React, extJS, ...)
― Мобильные приложения (Cordova и подобные, Native)
• Технологии InterSystems позволяют вам с лёгкостью создавать REST API
Вопросы?
Top Related