Проектирование и генерация REST API: Комплексное руководство с использованием Visual Paradigm

Введение

В современном мире разработки программного обеспечения прикладные программные интерфейсы (API) стали основой цифровой коммуникации между различными системами и сервисами. Среди различных архитектурных стилей для проектирования API REST (Representational State Transfer — передача представлений состояния) стал доминирующим подходом благодаря своей простоте, масштабируемости и безызвестному характеру. REST API позволяют различным программным приложениям обмениваться данными через интернет, используя стандартные протоколы HTTP, что делает их независимыми от платформы и широко доступными.

Однако проектирование, документирование и внедрение REST API может быть сложным и трудоемким процессом, особенно когда необходимо обеспечить согласованность, качественную документацию и удобство использования как для поставщиков, так и для потребителей сервисов. Здесь на помощь приходит Visual Paradigm — мощный инструмент моделирования, который оптимизирует весь жизненный цикл REST API от проектирования до развертывания.

В этом комплексном исследовании рассматривается, как Visual Paradigm упрощает полный процесс разработки REST API, охватывая все этапы — от начального проектирования с использованием диаграмм классов UML до генерации готового к производству кода и всесторонней документации API. Мы подробно рассмотрим как точку зрения поставщика (проектирование и внедрение API), так и точку зрения потребителя (доступ и использование API), предоставляя практические рекомендации по каждому этапу процесса.

---

Основы REST API

Что такое REST API?

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

REST API работают с ресурсами, которые идентифицируются с помощью унифицированных идентификаторов ресурсов (URI). Эти ресурсы обрабатываются с использованием стандартных методов HTTP, таких как GET, POST, PUT, PATCH и DELETE. Ключевые принципы REST включают:

• Безызвестность (Statelessness): Каждый запрос от клиента содержит всю необходимую информацию для его обработки

• Разделение клиент-сервер: Клиент и сервер работают независимо друг от друга

• Кэшируемость: Ответы должны явно указывать, являются ли они кэшируемыми

• Единый интерфейс: Стандартные методы для манипулирования ресурсами

Как Visual Paradigm поддерживает REST API

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

Следующая диаграмма деятельности показывает шаги, которые предпримет поставщик для создания REST API и соответствующей документации:

Диаграмма деятельности — Как поставщик может спроектировать и создать REST API?

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

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

Диаграмма деятельности — Как клиент может получить доступ к сервису с помощью REST API?

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

---

Часть 1: Проектирование REST API с помощью UML

Как спроектировать REST API с помощью UML?

Вы можете спроектировать свой REST API, создав диаграмму классов, которая представляет ваш ресурс, тело запроса и ответ.

Создание REST-ресурса

REST-ресурс — это фундаментальная единица веб-сервиса, соответствующего архитектуре REST. Это объект, обладающий URI, методом HTTP-запроса, связанными параметрами и телом запроса/ответа. Каждый REST-ресурс представляет конкретный сервис, доступный по пути, указанному в его свойстве URI. Поэтому, если вы хотите смоделировать несколько сервисов, создайте несколько REST-ресурсов.

Пошаговое руководство по созданию REST-ресурса

Шаг 1: Создать новую диаграмму классов

ВыберитеДиаграмма > Создать на панели инструментов приложения. В окнеНовая диаграмма выберитеДиаграмма классов и затем нажмитеДалее. Введите имя и описание диаграммы и затем нажмитеОК.

Шаг 2: Выберите инструмент REST-ресурс

ВыберитеREST-ресурс на панели инструментов диаграммы.

Выберите REST-ресурс на панели инструментов диаграммы

Шаг 3: Создайте REST-ресурс

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

REST-ресурс создан

Шаг 4: Откройте спецификацию ресурса

Щёлкните правой кнопкой мыши по REST-ресурсу и выберитеОткрыть спецификацию… в контекстном меню.

Открытие спецификации REST-ресурса

Шаг 5: Заполните общие свойства

ВОбщие вкладка, заполните следующее:

Свойство	Описание
URI	Каждый REST-ресурс имеет свой собственный URI. Потребители используют URL для доступа к REST-ресурсу. Обычно RESTful URI должен ссылаться на ресурс, который является объектом, а не на действие. Поэтому при определении URI старайтесь использовать существительное, а не глагол.
Метод	Указывает действие, выполняемое над ресурсом. Для подробностей прочитайте раздел Методы (HTTP-методы) ниже.
Описание	Описание ресурса, которое будет отображаться в сгенерированной API-документации. Рекомендуется предоставить четкое описание сервиса, чтобы потребитель понимал, что представляет собой сервис и как с ним работать.

Общие свойства REST-ресурса

URI, метод и описание заполнены

Шаг 6: Моделирование тела запроса (для POST, PUT, PATCH, DELETE)

Если REST-ресурс использует методы POST, PUT, PATCH или DELETE и если при использовании REST-ресурса требуются параметры, смоделируйте параметры, создав класс(ы). Наведите курсор мыши на Тело REST-запроса значок. Нажмите на Каталог ресурсов кнопку и перетащите её.

Создать класс из тела REST-запроса

Отпустите кнопку мыши и выберите Ассоциация -> Один класс из каталога ресурсов.

Выбрать один класс

Отпустите кнопку мыши, чтобы создать класс запроса. По умолчанию класс называется в соответствии с REST-ресурсом. При желании вы можете переименовать его. Например, если вы собираетесь создать члена через REST-ресурс /members, вам, вероятно, потребуется отправить детали члена на сервер для создания записи о члене. Поэтому назовите класс Член для хранения деталей члена.

Класс создан из тела REST-запроса

Добавьте атрибуты в классы. Эти атрибуты будут содержать данные, отправляемые на сервер.

Атрибуты добавлены

Ниже приведено сравнение модели класса и представления тела запроса в формате JSON.

Сравнение модели класса и тела запроса в формате JSON

Шаг 7: Моделирование тела ответа

Теперь вы можете перейти к проектированию части ответа REST-ресурса. Наведите курсор мыши на Тело ответа REST иконку. Если сервис вернет простое значение данных или объект, нажмите на Каталог ресурсов кнопку и перетащите её. Затем выберите Ассоциация -> Один класс из каталога ресурсов. Если сервис вернет массив объектов, выберите Ассоциация -> Множество классов из каталога ресурсов.

Создать класс из тела ответа REST

Назовите класс и добавьте атрибут в класс.

Класс создан из тела ответа REST

Ниже приведено сравнение модели класса и представления тела ответа в формате JSON.

Сравнение модели класса и тела ответа в формате JSON

Указание параметров для REST-ресурса, использующего GET

Параметры относятся к параметрам запроса, используемым для передачи данных сервису. Например, при использовании сервиса ‘конвертер валют’ вам, вероятно, потребуется передать сервису сумму для конвертации, текущую валюту и целевую валюту в обмен на конвертированную сумму. Следовательно, сумма для конвертации, текущая и целевая валюта являются параметрами сервиса.

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

Параметры добавляются к пути URL при отправке HTTP-запроса. URL с параметрами может выглядеть следующим образом: http://www.example.com?age-limit=18

Чтобы добавить параметры к REST-ресурсу:

1. Щелкните правой кнопкой мыши на REST-ресурсе и выберите Новый параметр из всплывающего меню.

Новый параметр

2. Введите имя параметра. При желании вы также можете указать тип. Обратите внимание, что указание типа предназначено исключительно для документации. Хотя это помогает потребителю понять, какие данные ожидаются, это не окажет никакого влияния на уровне кода. При программировании параметры всегда помещаются в Map, где и ключ, и значение являются строками.

Параметр создан

3. Нажмите Введите.

4. Повторите шаги 2 и 3 для создания всех параметров. НажмитеEsc после завершения создания всех параметров.

Параметры созданы

Моделирование нескольких сценариев

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

Пример:

Случай 1:

• Заголовок ответа: status : 200 OK

• Тело ответа: {“customer” : {“name” : “Peter”}}

Случай 2:

• Заголовок ответа: status : 400 Bad Request

• Тело ответа: {“customer”: {“error” : {“text” : “Invalid customer name.”}}}

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

Создание второго тела ответа

---

Часть 2: Указание заголовков и примеров

Указание заголовка запроса и примера запроса

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

1. Щелкните правой кнопкой мыши на REST-ресурсе и выберитеОткрыть спецификацию… из всплывающего меню.

2. ОткройтеТело запроса вкладку.

3. ВведитеЗаголовок. Как мы уже говорили на странице «Обзор REST API», REST — это не стандарт, а архитектурный стиль. REST использует стандарт HTTP, поэтому любой заголовок запроса REST на самом деле является заголовком HTTP.

4. Введите Пример в формате JSON.

Заголовок запроса и пример указаны

Указание заголовка ответа и примера ответа

Аналогично вам необходимо указать заголовки ответа и пример ответа (тела). В результате заголовок ответа и пример будут отображены в сгенерированной документации API.

1. Щелкните правой кнопкой мыши на REST-ресурсе и выберите Открыть спецификацию… из всплывающего меню.

2. Откройте Тело ответа вкладку.

3. Введите Заголовок.

4. Введите Пример в формате JSON.

Заголовок ответа и пример указаны

Заголовки (HTTP-заголовки)

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

GET / HTTP/1.1
Host: www.visual-paradigm.com
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:33.0) Gecko/20100101 Firefox/33.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Cookie: landing=b7b93a316f374b13af4d5904c9797dcc; __utma=...
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

Как мы уже говорили ранее, REST — это не стандарт, а архитектурный стиль. REST использует стандарт HTTP. Следовательно, любые заголовки вызова REST на самом деле являются заголовками HTTP.

Методы (HTTP-методы)

HTTP-методы, иногда называемые HTTP-глаголами, определяют действие, выполняемое над ресурсом. Наиболее часто используемые HTTP-методы — GET, PUT, POST и DELETE, которые соответственно соответствуют операциям чтения, обновления, создания и удаления.

Метод	Описание
GET	Метод GET (или запрос GET) используется для получения представления ресурса. Он должен использоваться ТОЛЬКО для получения данных и не должен их изменять.
PUT	Метод PUT (или запрос PUT) используется для обновления ресурса. Например, если вы знаете, что запись в блоге находится по адресу http://www.example.com/blogs/123, вы можете обновить эту конкретную запись, используя метод PUT для размещения новой представления ресурса записи.
POST	Метод POST (или запрос POST) используется для создания ресурса. Например, когда вы хотите добавить новую запись в блог, но не знаете, где её разместить, вы можете использовать метод POST для отправки её по URL-адресу и позволить серверу определить URL.
PATCH	Метод PATCH (или запрос PATCH) используется для изменения ресурса. Он содержит изменения, вносимые в ресурс, а не полное представление ресурса.
DELETE	Метод DELETE (или запрос DELETE) используется для удаления ресурса, идентифицированного URI.

Описание различных методов HTTP

---

Часть 3: Генерация REST API из UML

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

Генерация REST API (с точки зрения поставщика)

Для генерации REST API:

1. Выберите Инструменты > Код > Сгенерировать REST API… на панели инструментов.

2. В окне REST API выберите Поставщик для Тип API. Таким образом, вы сможете сгенерировать документацию к API, а также пример кода сервера, который поможет вам в программировании вашего сервиса (логики).

Выберите REST-ресурс для генерации

3. Выберите REST-ресурс для генерации кода.

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

5. Отметьте Сгенерировать документацию к API для генерации HTML-файлов, демонстрирующих, как использовать выбранный(е) REST-ресурс(ы). Предполагается, что вы опубликуете сгенерированную документацию API на своём сайте, чтобы потребители вашего сервиса могли ознакомиться с ней и узнать, как получить доступ к вашему сервису.

6. Введите название вашей компании, которое будет отображено в документации API.

7. Введите базовый URL ваших сервисов.

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

9. Введите путь вывода кода.

Путь вывода указан

10. НажмитеСгенерировать. В зависимости от выбранной/невыбранной опции вы можете увидеть следующие папки в выходном каталоге:

Папка	Описание
doc	Документация API. Вы должны опубликовать документацию API на своём сайте, чтобы потребители вашего сервиса могли ознакомиться с ней и изучить API.
lib	Для работы сгенерированного кода библиотека Google Gson должна быть доступна в вашем class path. Скачайте библиотеку вручную по адресу https://code.google.com/p/google-gson/ и поместите файл в папку lib.
sample_src	Пример кода клиента и сервлета. Он показывает, как получить доступ в качестве клиента и как реагировать на запрос в качестве поставщика. Мы настоятельно рекомендуем вам скопировать код и изменить его, внедрив свою собственную логику сервиса.
src	Исходный код модели коммуникации. Не изменяйте содержимое файла, иначе код может перестать работать корректно.

Описание сгенерированных файлов

---

Часть 4: Как использовать сгенерированный REST API?

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

Пошаговое руководство для потребителей

Шаг 1: Посетите документацию API

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

Документация REST API

Шаг 2: Скачайте XML-модель REST API

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

Скачать XML-модель REST API

Шаг 3: Скачайте и установите Visual Paradigm

Скачайте Visual Paradigm с официального сайта. Установите и запустите его.

Шаг 4: Импортируйте XML-файл

Импортируйте XML-файл модели REST API в Visual Paradigm, выбравПроект > Импортировать > XML… на панели инструментов.

Шаг 5: Укажите параметры импорта

В окнеИмпорт XML введите путь к файлу XML и нажмитеИмпортировать.

Окно импорта XML

Шаг 6: Откройте диаграмму классов

На вкладкеДиаграммы вОбозревателе проекта дважды щёлкните на диаграмме классов, созданной путём импорта XML-файла.

Откройте диаграмму классов

Шаг 7: Просмотр модели коммуникации

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

Модель коммуникации

Шаг 8: Сгенерируйте код API

ВыберитеИнструменты > Код > Сгенерировать REST API… на панели инструментов.

Шаг 9: Выберите тип API — Потребитель

В окнеREST API окно, выберите Потребитель как Тип API.

Выберите потребителя в качестве типа API

Шаг 10: Выберите REST-ресурс и настройте генерацию

Выберите REST-ресурс для генерации кода.

Выберите REST-ресурс, который необходимо сгенерировать

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

Путь вывода указан

Шаг 11: Сгенерируйте и используйте код

Нажмите Сгенерировать. В зависимости от выбранной/невыбранной опции вы можете увидеть следующие папки в каталоге вывода:

Папка	Описание
lib	Чтобы сгенерированный код работал, библиотека Google Gson должна быть доступна в вашем class path. Скачайте библиотеку вручную по адресу https://code.google.com/p/google-gson/ и поместите файл в папку lib.
sample_src	Пример кода, который показывает, как получить доступ к сервису. Мы настоятельно рекомендуем вам скопировать код и изменить его, внедрив собственную логику приложения.
src	Исходный код модели коммуникации. Не изменяйте содержимое файла, иначе код может работать некорректно.

Описание сгенерированных файлов

---

Заключение

Visual Paradigm предлагает комплексное и эффективное решение для проектирования, документирования и генерации REST API. Используя диаграммы классов UML, разработчики могут визуально моделировать ресурсы API, тела запросов и ответов, а также различные сценарии, обеспечивая ясность и согласованность на протяжении всего процесса разработки.

Ключевые преимущества использования Visual Paradigm для разработки REST API

1. Визуальное проектирование: Возможность визуального проектирования REST API с использованием диаграмм UML делает процесс более интуитивным и доступным, сокращая кривую обучения для членов команды и заинтересованных сторон.

2. Согласованность: Генерируя код и документацию из единого источника истины (модели UML), Visual Paradigm обеспечивает согласованность между проектированием, реализацией и документацией.

3. Генерация документации: Автоматическая генерация полной документации API экономит значительное время и гарантирует, что документация остается в синхронизации с фактической реализацией.

4. Генерация кода: Генерация примеров кода как для поставщиков, так и для потребителей ускоряет разработку и снижает вероятность ошибок при реализации модели коммуникации API.

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

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

Рекомендации по проектированию REST API с использованием Visual Paradigm

• Используйте существительные для URI: При проектировании URI используйте существительные для представления ресурсов, а не глаголы для действий.

• Определите четкие описания: Предоставляйте четкие описания для ваших ресурсов, параметров и примеров, чтобы потребители понимали, как использовать ваш API.

• Моделируйте все сценарии: Включайте как сценарии успешных ответов, так и сценарии ошибок, чтобы предоставить полную картину поведения вашего API.

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

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

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

Будущие соображения

По мере того как ландшафт разработки программного обеспечения продолжает развиваться, инструменты, такие как Visual Paradigm, поддерживающие визуальное моделирование и генерацию кода, будут становиться все более ценными. Они позволяют командам:

• Поддерживать согласованность в рамках крупных команд и сложных систем

• Сократить время разработки за счёт автоматизации

• Повысить качество путём устранения ошибок ручного перевода

• Улучшить взаимодействие между различными заинтересованными сторонами

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

---

Ссылки

1. Обзор REST API: Обзор концепций REST API и поддержки Visual Paradigm для генерации REST API

2. Моделирование REST API с помощью UML: Подробное руководство по проектированию REST API с использованием классовых диаграмм UML в Visual Paradigm

3. Как спроектировать REST API с помощью UML: Практические шаги по проектированию REST API с использованием диаграмм UML

4. Как сгенерировать REST API из UML: Пошаговые инструкции по генерации кода REST API из моделей UML

5. Как использовать сгенерированный REST API: Руководство для потребителей по использованию сгенерированного кода REST API

6. Учебные материалы Visual Paradigm: Коллекция учебных материалов для начала работы с Visual Paradigm

7. YouTube-канал Visual Paradigm: Видео-ресурсы и демонстрации

8. База знаний Visual Paradigm: База знаний с советами, приёмами и решениями

9. Поддержка Visual Paradigm: Информация о поддержке и контактные данные