HATEOAS Как связаться с не-HATEOAS внешними ресурсами

Содержание

Вопрос или проблема
Ответ или решение
HATEOAS: Как связываться с не-HATEOAS внешними ресурсами
Основные принципы
Сценарии
Сценарий 1: Внешний ресурс – JSON API без HAL
Сценарий 2: Внешний ресурс, не имеющий API
Заключение

Вопрос или проблема

У меня есть HATEOAS (HAL на https://example.com/api) бэкенд и SPA (Angular на https://example.com/spa) в качестве фронтенда.

Поскольку все мои ссылки находятся в моем собственном API, и ответы имеют формат HAL, мой фронтенд SPA знает, как их отображать в интерфейсе.

Но что я должен вернуть в качестве ссылки, если мне нужно указать на внешний ресурс, который может даже не возвращать HAL, и мой фронтенд не имеет представления о том, как его интерпретировать?

Что насчет следующих сценариев:

Внешний ресурс — это JSON API, который не возвращает HAL (например, https://external.com/api), но есть фронтенд, который знает, как интерпретировать этот ресурс (например, https://external.com/frontend). Должен ли я вернуть ссылку на API (как и на все другие ссылки, указывающие на мой собственный API), или мне следует вернуть ссылку на фронтенд? Как мой фронтенд должен знать, что он не может это отобразить и каким-то образом перенаправить пользователя на внешний фронтенд?
Внешний ресурс не имеет API, а только фронтенд (например, https://external.com/). Как мой фронтенд должен знать, что он не может это отобразить и каким-то образом перенаправить пользователя на внешний фронтенд?

Ответ или решение

HATEOAS: Как связываться с не-HATEOAS внешними ресурсами

В контексте разработки программного обеспечения с использованием архитектурного стиля HATEOAS (Hypermedia as the Engine of Application State), особенно когда речь идет о взаимодействии между бэкендом на основе HAL и фронтендом (например, на основе Angular), может возникнуть необходимость ссылки на внешние ресурсы, которые не поддерживают HATEOAS. Рассмотрим, как правильно реализовать такие ссылки.

Основные принципы

Определение контекста: Важно понимать, что API, использующий HATEOAS, предназначен для управления состоянием приложения через гипермедиа. Это означает, что ваше приложение ожидает и знает, как обрабатывать ответы в определенном формате (в данном случае HAL).
Универсальный подход к ссылкам: При наличии возможности возвращать ссылки на внешние ресурсы следует придерживаться предсказуемого подхода. Если ссылка возвращается на внешний API или веб-сайт, это должно быть сделано в соответствии с установленными стандартами, включая четкое документирование.

Сценарии

Сценарий 1: Внешний ресурс – JSON API без HAL

Рекомендованное решение: В этом случае лучше всего предоставить ссылку на фронтенд внешнего ресурса. Это связано с тем, что пользователю, вероятно, будет удобнее взаимодействовать с UI, чем с API, о котором он не имеет информации. Для реализации этого можно использовать следующие подходы:
- Верните ссылку на API, добавив к ней специальное поле, которое указывает, что этот ресурс не является HATEOAS. Например:
```
{
    "_links": {
        "self": { "href": "https://example.com/api/resource" },
        "external_frontend": { "href": "https://external.com/frontend", "type": "text/html", "note": "Этот ресурс не поддерживает HAL" }
    }
}
```
- В вашем текущем фронтенде можно добавить логику для определения, является ли ссылка внешней и, в таком случае, перенаправлять пользователя на страницу, совместимую с его ожиданиями.
Необходимость валидации: Убедитесь, что ваша система может проверять, какие ссылки ведут к API, а какие к фронтенду, для предотвращения путаницы для пользователя.

Сценарий 2: Внешний ресурс, не имеющий API

Рекомендованное решение: Для таких случаев необходимо возвращать ссылку на веб-сайт. Примеры реализации могут включать:
- Предоставление ссылки в виде обычного элемента, например:
```
{
    "_links": {
        "self": { "href": "https://example.com/api/resource" },
        "external_website": { "href": "https://external.com/", "note": "Внешний ресурс без API" }
    }
}
```
- Ваш фронтенд может обрабатывать ответ и проверять наличие определенных ключей или атрибутов, чтобы определить, как действовать с этими ссылками.

Заключение

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

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