Зачем нужна «обнаруживаемость» в REST API, когда клиенты в любом случае недостаточно развиты, чтобы использовать его?

Различные доклады, которые я смотрел, и учебники, которые я сканировал на REST, подчеркивают нечто, называемое «открываемостью». Насколько я понимаю, этот термин, по-видимому, означает, что клиент должен иметь возможность пойти http://URLи автоматически получить список того, что он может сделать.

Что мне трудно понять, так это то, что «программные клиенты» - это не люди. Это просто программы, которые не имеют интуитивных знаний, чтобы понять, что именно делать с предоставленными ссылками. Только люди могут зайти на веб-сайт и понять текст и ссылки, представленные и действовать на нем.

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

Потребность в обнаружении может быть неактуальной, но ссылки, которые позволяют обнаружение, служат большему количеству целей. Самым важным из них, на мой взгляд, является то, что предоставление полных URI в ответах клиенту означает, что ни одному клиенту никогда не потребуется «составлять» URI. Это означает, что ни одному клиенту никогда не понадобятся знания о том, как структурированы URI. А это, в свою очередь, позволяет разработчикам серверов изменять схему URI всякий раз, когда им это удобно, поскольку им не нужно учитывать старых клиентов, все еще полагающихся на старый способ структурирования URI.

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

Например, Jenkins (сервер CI) имеет REST-подобный интерфейс. Перейдите на любую страницу, добавьте в URL адрес «/ api», и вы получите страницу, описывающую все, что вы можете сделать. Это делает изучение API тривиальным. Например, http://ci.jruby.org приводит вас на сервер jenkins для jruby, а http://ci.jruby.org/api - в API для этой конкретной страницы.

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

Как только мне удалось получить фактический ответ от сервера, стало возможным сравнить документацию с ответом сервера и использовать ее для расшифровки документации (и да, расшифровка была правильным термином). Проблема заключалась в том, что если на сервер был отправлен запрос, который был не совсем корректным в соответствии со спецификацией, вы бы просто получили ошибку, а с нечитаемой документацией выяснить, как отправить правильные запросы, было почти невозможно. Существовали также разные версии документации API, которые не соглашались друг с другом и, вероятно, не соглашались с самим API; это не помогло

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

ПРИМЕЧАНИЕ: я не специалист по этому вопросу, но я несколько раз пытался примирить различные нюансы интерпретации людьми «REST», и это был вывод, который я получил, изучив его на время.

Насколько я понимаю, это происходит из « Гипермедиа» Роя Филдинга как «движка прикладного состояния», известного как «HATEOAS», который затем становится движущей силой идеи «семантической сети».

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

Если вы просто используете «REST» для симпатичных URL-адресов, сопоставленных с операциями CRUD, о которых потребитель должен предварительно знать и звонить в соответствии с хорошо известным контрактом, Рой Филдинг считает, что это не совсем RESTful.

Это не означает, что настройка службы RPC со вкусом REST не может быть полезной / улучшением по сравнению с более сложной моделью RPC и пригодной для ограниченного / контролируемого использования, но сторонники жесткой линии посмотрит на это и посчитают ее вырожденной. / не совсем ОТДЫХ.