REST API, зная формат добавления элемента в пустой список
Еще один приятный выбор - использовать MultiValuedMap из Apache Commons. Взгляните на все известные классы реализации в верхней части страницы для специализированных реализаций.
Пример:
HashMap> map = new HashMap>()
можно заменить на
MultiValuedMap map = new MultiValuedHashMap();
Таким образом,
map.put(key, "A");
map.put(key, "B");
map.put(key, "C");
Collection coll = map.get(key);
приведет к сбору coll, содержащему «A», «B» и «C».
2 ответа
Стандарт OpenAPI
Хорошим способом предоставления стандартизированной, обнаруживаемой информации и примеров обо всех форматах ввода / вывода ваших API-интерфейсов является стандарт OpenAPI . По сути, это стандарт для спецификации YAML REST-подобных API-форматов с поддерживающей инфраструктурой ( Swagger ), который позволяет легко преобразовать эту спецификацию в удобочитаемую документацию, действительные примеры входных и выходных данных, а также для составления кода на многих языках программирования и средах, которые будут отправлять данные в / из документированного API.
Для начала может быть интересной Swagger page или практическая демонстрация редактора .
Откуда вы знаете формат публикации данных в API, основанный на отдыхе, если нет документации?
Сервер должен научить клиента, как должен выглядеть запрос. В HTML, т. Е. Это делается через веб-форму, которая включает в себя все элементы, которые поддерживает сервер. В случае обновления поля могут быть автоматически заполнены текущими значениями, которые могут быть изменены пользователем / приложением. Поскольку форма также содержит URI для отправки данных, клиент может просто инициировать запрос, вызвав кнопку отправки формы.
Для REST API подобный подход может и должен быть принят. Здесь сервер может дать клиенту подсказку о поддерживаемых типах мультимедиа (в зависимости от того, поддерживает ли тип мультимедиа, полученный клиентом, такую функцию), что также можно найти с помощью операции
OPTIONS, которая информирует клиента о возможности конечной точки, такие как поддерживаемые типы медиа или операции, которые могут быть вызваны на конечной точке.Должен ли метод get для коллекции возвращать пример элемента?
Если клиенту предоставляется форма, объясняющая, как должен выглядеть запрос, то нет Здесь действительно требуется информация о полосе, поэтому она не нужна.
Поскольку вы связали модель зрелости Ричардсена (RMM): IMO, эта модель не имеет особого смысла с точки зрения REST. Во-первых, в любом случае не существует приверженности REST до уровня 3, и даже при наличии уровня 3 у вас нет гарантии того, что вы действительно соответствуете архитектуре REST.
1113 Это, вероятно, нуждается в дополнительном объяснении, я полагаю. REST - это модель взаимодействия, а не протокол. Он использует свойства, которые сделали Интернет столь успешным, как, например, простое масштабирование посредством связи без сохранения состояния и снижение рабочей нагрузки за счет кэширования ответов на промежуточных серверах или распределения запросов между серверами с балансировкой нагрузки. Одна из его целей - разделение клиентов и серверов, позволяя последнему свободно развиваться, не опасаясь взлома первых. Таким образом, сервер должен обучать клиента всему, что ему нужно, чтобы сделать осознанный выбор, над какими «действиями» следует действовать дальше.
Т.е. сервер предоставит все ссылки, которые могут понадобиться клиенту, включая некоторые сопровождающие имена отношений ссылок, где имена отношений дают URI именованный контекст, который клиент может использовать, чтобы решить, вызывать его или нет. Такие имена либо стандартизированы IANA , либо должны быть абсолютными URI, как определено в RFC 8288 - Web Linking , т.е. как Dublin Core . Эта концепция позволяет серверу в любое время изменять URI ресурсов. Клиенты, уважающие эту концепцию, по-прежнему смогут выполнять свою задачу, в то время как клиенты, анализирующие и анализирующие такие URI, могут в результате этого сломаться.
Согласно Филдингу
API REST должен тратить почти все свои описательные усилия на определение типа (типов) мультимедиа, используемых для представления ресурсов и управления состоянием приложения, или на определение имен расширенных отношений и / или гипертекстовая разметка для существующих стандартных типов носителей. Любые усилия, затраченные на описание того, какие методы использовать для каких интересующих URI, должны быть полностью определены в рамках правил обработки для типа носителя (и, в большинстве случаев, уже определены существующими типами носителя) ( Источник )
Кроме того, Филдинг упомянул, что клиенты не должны относить ресурсы к определенному типу , а вместо этого договариваются с сервером о поддерживаемых форматах представления, понятных обоим приложениям. через согласование типа контента. Клиент, ожидающий, что конечная точка
http://acmee.com/api/usersвернет представление JSON с предопределенными полями, может иметь определенные проблемы, если ответ поставляется с другими именами полей или с другими типами значений, или вообще с другой структурой, отличной от ожидаемой. Это также напрямую связывает клиента с возвращаемым значением определенного API и, таким образом, требует определенных внеполосных знаний. Это то, чего не хватает в RMM. Поэтому, даже если вы достигли уровня 3 в RMM, вы все равно можете не соблюдать все ограничения, которые Fielding накладывает, чтобы придерживаться стиля архитектуры REST.