Какой URI можно использовать для запроса ресурса по умолчанию?

Question

При создании новых ресурсов в моем REST API я хочу дать пользователю возможность запросить пустой ресурс, который уже содержит некоторые значения по умолчанию. Поскольку у него нет идентификатора как такового, я не совсем уверен в URI RESTful, который я мог бы использовать. Некоторые идеи:

http://example.com/resource/_ 
http://example.com/resource/__new 

Любые предложения или опыт с этой проблемой?

Answer 1

Я думаю, что это скорее пользовательский интерфейс, чем API-объект, то есть пользовательский интерфейс должен предварительно заполнять значения по умолчанию в соответствующие поля формы для пользователя, которые затем просто заполнят пробелы и настраивают по умолчанию если необходимо. Это не применимо везде (например, когда у вас есть только API без бита пользовательского интерфейса).

Вы уже предложили некоторые варианты самостоятельно - они будут работать, однако при условии, что вы можете получить доступ к существующим ресурсам, как /resource/123, оба варианта сломают ваш дизайн URI хотя бы немного. Я могу думать о трех альтернативах того, как подойти к этому, последний (третий) вариант может быть лучшим выбором.

Подход № 1
Лучше подход может имитировать способ, как время-ресурсоемких задач, как правило, делается в REST. Обычно у вас есть ресурс, к которому вы отправляете задание, затем служба отвечает на URI задачи, который позже можно использовать для проверки выполнения задачи. Мы можем адаптировать его к нашему случаю - определить пустые ресурсы со значениями по умолчанию в качестве нового ресурса, которые мы можем использовать для получения «шаблона» для другого ресурса.

Пример:
Предполагая, что вы хотите получить шаблон для ресурса под названием «пользователь». Вы бы сначала сделать запрос POST для шаблона ресурса и указать тип ресурса, для которого вы хотите создать «шаблон»:

POST /template/ 

<?xml version="1.0" encoding="UTF-8" ?> 
<template> 
    <type>user</type> 
</template> 

API-интерфейс будет создавать новый «по умолчанию» ресурс для указанного типа , в случае успеха он ответит бы с:

HTTP/1.1 204 No Content 
Location /user/123 

место указано в ответе вашего API, будет содержать шаблон для ресурса:

GET /user/123 

<?xml version="1.0" encoding="UTF-8" ?> 
<user> 
    <id>123</id> 
    <name /> 
    <email /> 
    <preferred-language>en</preferred-language> 
    <timezone>UTC</timezone> 
    ... 
</user> 

Подход №2
Подход №1 уже создает для вас ресурс. Альтернативный подход - предоставить пользователям доступ к шаблонам для получения определенного URI.

Пример:

GET /template/user 

<?xml version="1.0" encoding="UTF-8" ?> 
<user> 
    <name /> 
    <email /> 
    <preferred-language>en</preferred-language> 
    <timezone>UTC</timezone> 
    ... 
</user> 

Подход № 3
Существует еще одна альтернатива - я считаю, что это самый простой и логичный подход, но он может не подходить для всех случаев. Вы можете создать пустой ресурс с настройками по умолчанию, выполнив запрос POST непосредственно к ресурсу, с которым вы хотите работать.Одним из недостатков может быть то, что это не позволит пользователям просто просматривать шаблон (который они могли бы использовать в подходе № 1), он всегда будет создавать для них ресурс (аналогично подходу № 1).

Пример:
Для того, чтобы получить версию по умолчанию ресурса вы бы отправить запрос пустой POST к этому ресурсу:

POST /user/ 

API-интерфейс позволит создать новый ресурс со значениями по умолчанию и отвечать с:

HTTP/1.1 204 No Content 
Location /user/123 

же, как и в подходе # 1, URI позволит пользователю получать созданный ресурс, а затем изменить его по мере необходимости (через PUT):

GET /user/123 

<?xml version="1.0" encoding="UTF-8" ?> 
<user> 
    <id>123</id> 
    <name /> 
    <email /> 
    <preferred-language>en</preferred-language> 
    <timezone>UTC</timezone> 
    ... 
</user>