Различные доклады, которые я смотрел, и учебники, которые я сканировал на REST, подчеркивают нечто, называемое «открываемостью». Насколько я понимаю, этот термин, по-видимому, означает, что клиент должен иметь возможность пойти http://URL
и автоматически получить список того, что он может сделать.
Что мне трудно понять, так это то, что «программные клиенты» - это не люди. Это просто программы, которые не имеют интуитивных знаний, чтобы понять, что именно делать с предоставленными ссылками. Только люди могут зайти на веб-сайт и понять текст и ссылки, представленные и действовать на нем.
Так в чем же смысл обнаружения, когда клиентский код, который обращается к таким обнаруживаемым URL-адресам, на самом деле ничего не может с этим поделать, если только разработчик клиента на самом деле не экспериментирует с представленными ресурсами? Это похоже на то же самое, что и определение набора доступных функций в руководстве по документации, просто с другой стороны, и фактически требует больше работы для разработчика. Почему этот второй подход предварительного определения того, что может быть сделано в документе, внешнем по отношению к фактическим ресурсам REST, считается неполноценным?
«Клиенты» могут быть недостаточно продвинуты, чтобы использовать их, но пользователи клиентов могут. В конце концов, клиент может быть таким же простым, как веб-браузер. Обнаруживаемость - это все, что позволяет людям изучать и использовать 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 и пригодной для ограниченного / контролируемого использования, но сторонники жесткой линии посмотрит на это и посчитают ее вырожденной. / не совсем ОТДЫХ.
источник