Как лучше всего описать тот факт, что новые элементы могут быть созданы с помощью запроса PUT с ограничением HATEOAS, т. Е. Где клиент будет указывать {id}?
Как бы вы сделали это на веб-сайте?
Возможно, у вас есть какой-то ресурс, который предоставляет форму; и форма будет включать в себя id и, возможно, другие интересные вещи. Клиент заполнил бы форму (используя семантические подсказки для интерпретации, какая информация принадлежит каждому полю) Когда форма отправляется, правила обработки HTML будут кодировать значения формы в представление application/x-www-url-formencoded, которое станет частью запроса для целевого URL. Сервер проверяет полезную нагрузку, вычисляет соответствующий целевой URI и отправляет клиенту ответ на перенаправление.
Клиент может затем GET / PUT / POST и т. Д. К ресурсу, рекомендованному сервером.
Если вы немного косите, вы можете увидеть, что форма играет роль, очень похожую на шаблон URI .
Таким образом, основной эскиз довольно прост: клиент и сервер должны согласовать тип носителя, который описывает шаблон (и его семантическое значение), и соответствующие правила обработки.
Вот плохие новости: это немного сложно. Во всемирной паутине HTML делает тонну тяжелой работы для нас. Если ваш API также использует html-представления своих ресурсов, то вы можете вернуться к уже существующим формам. Но HTML отчасти вышел из моды.
В пространстве API у JSON много общего, и есть несколько типов носителей, которые используют его в качестве отправной точки. Опрос Сукочеффа за 2014 год сейчас пять лет, но он даст вам некоторое представление о том, что там есть.