REST API POST / PUT с различным набором запросов

Question

Может ли метод post или put, который создает / изменяет ресурс, принимать другой набор объектов запроса?

Например: у меня есть ресурс с именем 'server'.Его можно отличить по своей ОС.например, у меня может быть два экземпляра ресурса - windows server и linux server.Мое основное решение здесь состоит в том, чтобы рассматривать их как один и тот же тип ресурса, т. Е. server.

. Теперь может случиться так, что для создания сервера Windows мой POST API принимает объект запроса, отличный от того, который будет принимать тот же API.для Linux-сервера.

Для создания Windows-сервера у меня есть -

POST : /v1/server
accepts 
{
    name : win-server-1
    os : 'windows'
    ms-office: 'Office2009'
}

Для создания Linux-сервера я использую тот же API, но использую другой объект запроса -

POST : /v1/server
accepts
{
   name : linux-server-1,
   os : 'linux'
   kernel-version : '3.10.0' 
}

КакВы можете видеть, что запросы, принятые одним и тем же POST API, различны для Windows и Linux-сервера.Моя бизнес-логика будет обрабатывать эти запросы на основе атрибута 'os'.Так что технически это будет работать (с ужасными случаями переключения).Но действительно ли это покой?Или у меня должны быть разные API, такие как /v1/windows-server и /v1/linux-server, и для каждого из них должны быть определены уникальные определения запросов?

Answer 1

Из POV клиента лучше иметь одну конечную точку.Обратите внимание, что наличие отдельных ресурсов переместит необходимость «некрасивого переключения» на клиента.

Я бы пошел с вашим текущим решением.Удобство клиента и ясность / простота API важнее, чем у разработчика.API важнее реализации.И ИМХО, ваше текущее решение лучше в этом отношении:

• create: POST /v1/servers
• fetch: GET /v1/servers/{server_id} POST /v1/servers/{server_name} (имя уникально) возвращает один ресурс
• query: GET /v1/servers/?{filter_expression} (например, GET /v1/servers/?os=linux) возвращает коллекцию (отфильтрованных) ресурсов (желательно с нумерацией страниц)

Одна вещь, которую я бы изменил, - это извлечь OS-конкретный материал для вложенного ресурса.Это сделает реализацию проще и API станет еще понятнее:

{
    name : win-server-1,
    os : 'windows',
    config: {
        ms-office: 'Office2009'
    }
}

{
    name : linux-server-1,
    os : 'linux',
    config: {
        kernel-version : '3.10.0' 
    }
}

Answer 2

Но действительно ли это покой?

Хороший способ проверить этот вопрос - спросить, насколько близко то, что вы пытаетесь сделать, соответствует сети.

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

windows: <form action="/v1/server" method="post">
    <!-- ... -->
    Office: <input type="text" name="config.office"><br>
    <input type="submit" value="Submit">
</form> 

linux: <form action="/v1/server" method="post">
    <!-- ... -->
    Kernel-version: <input type="text" name="config.kernel-version"><br>
    <input type="submit" value="Submit">
</form>

Любой веб-клиент, соответствующий стандартам, справится с этим просто отлично.Правила обработки для медиа-типа text/html говорят клиенту, как создать запрос из каждой из этих форм.

Обратите внимание, что, поскольку браузер просто обрабатывает form.action, вы можете легко изменить идентификатор ресурса.,Поэтому, если позже вы решите, что запросы Windows и Linux должны использовать разные запросы, вы можете сделать это достаточно легко:

windows: <form action="/v1/windows-server" method="post">
    <!-- ... -->
    Office: <input type="text" name="config.office"><br>
    <input type="submit" value="Submit">
</form> 

linux: <form action="/v1/linux-server" method="post">
    <!-- ... -->
    Kernel-version: <input type="text" name="config.kernel-version"><br>
    <input type="submit" value="Submit">
</form>

Но действительно ли это покой?

Быть «по-настоящему спокойным» не имеет ничего общего с тем, как ваш сервер обрабатывает запрос - гораздо важнее понимание того, как сервер описывает запросы к клиенту (иначе говоря, hypermedia ).

Answer 3

Я бы пошел на /v1/server/linux и /v1/server/windows.Это позволит вам сохранить /v1/server, например, для GET.

POST : /v1/server - как вы сказали, для этого потребуется больше кода и некоторые "случаи уродливого переключения" .Этот подход будет также сложнее поддерживать и развивать, когда кто-то попросит вас добавить новые типы серверов.

/v1/linux-server и /v1/windows-server - я думаю, что это также хороший подход.Только с двумя типами это не имеет большого значения иметь отдельные конечные точки.С большим числом /v1/server/{os_type} выглядит лучше в документации и более читабельно, чем список отдельных конечных точек X.