Я пытаюсь применить подход Hydra / JSON-LD к моему REST API, но я пытаюсь понять цели ApiDocumentation в целом.
Чтение Спецификация Hydra Core не смогла решить мои проблемы, но мне интересно, верно ли следующее, и надеюсь, что если это не так.
- "ApiDocumentation" представляет словарь данного API.
- Используется клиентами для просмотра подробностей ответов от API (например, поддерживаемые «Операции»)
- «ApiDocumenation» позволяет отключить отдельные поддерживаемые «Операции», установив«Требуется» свойство для «нуля» или даже для скрытия всей «Операции», просто вынимая его из документации.
Если 3) правильно, это означает, что сервер API должен содержать изменяемыйэкземпляр «ApiDocumentation» для каждого соединения, чтобы удовлетворить произвольные условия для поддерживаемых «операций» (например, вошел в систему пользователя).В дополнение к этому, это заставит клиента искать «ApiDocumentation» для изменений каждый раз, когда он получает ответ.
Я думаю, что все еще возможно отправить поддерживаемые «Операции» прямо в ответ APIно в этом случае документация, вероятно, очень скоро потеряет свою согласованность.
Возможно, я что-то здесь упускаю, но я не смог выяснить механизм предоставления «Операций» клиенту, даже после анализа словарного запаса API Demo от Маркуса Ланталера.
Обновление 2019/02/12
В результате анализа HydraConsole и JSON-LD Источники, я понял, что мое третье (3) предположение неверно.
ApiDocumentation всегда будет предоставлять клиенту всю документацию.Условные ресурсы (например, my_account в API Demo ) будут опущены в ответе сервера, если условие не относится.
Теперь мне все еще интересно, если второе (2) предположениеЗначение true или если лучше добавить информацию, такую как предоставленные «Операции», непосредственно в ответе сервера.