Question

When creating new resources in my REST API I want to give the user the possibility to request an empty resource that already contains some default values. Since it doesn’t have an ID per se I am not entirely sure about a RESTful URI that I could use though. Some ideas:

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

Any suggestions or experience with that issue?

Answer 1

I think that this is more a UI-thing than an API-thing – i.e. the UI should pre-fill the default values into respective form fields for the user, who would then just fill in the blanks and customize the default values if necessary. This is not however applicable everywhere (e.g. when you only have an API without the UI bit).

You already suggested some options yourself – these would work, however assuming that you can access existing resources as /resource/123, both options would break your URI design at least a bit. I can think of three alternatives on how to approach this, the last (third) one might be the best choice.

Approach #1
A better approach might be to mimic the way how time-intensive tasks are usually done in REST. You usually have a resource to which you POST a task, the service then replies with a task URI which you can use later to check on the progress of the task. We can adapt it to our case – define the empty resources with default values as a new resource which we can use to get a “template” for a different resource.

Example:
Assuming that you want to get a template for a resource called “user”. You would first do a POST request to the template resource and indicate the type of the resource for which you want to create a “template”:

POST /template/

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

The API would create a new “default” resource for the specified type, in case of success it would respond with:

HTTP/1.1 204 No Content
Location /user/123

The location specified in your API’s reply would then contain the template for the resource:

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>

Approach #2
Approach #1 already creates a resource for you. An alternative approach is to allow users access to get templates on a specific URI.

Example:

GET /template/user

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

Approach #3
There is one more alternative – I believe it’s the simplest and most logical approach, but it may not be suitable for all cases. You can create a empty resource with defaults by doing a POST request directly to the resource which you want to work with. One downside might be that this will not allow users to just view a template (which they could in approach #1), it will always create a resource for them (similarly as approach #1).

Example:
In order to get a default version of a resource you would send an empty POST request to that resource:

POST /user/

The API would create a new resource with default values and respond with:

HTTP/1.1 204 No Content
Location /user/123

Same as in approach #1, the URI would allow the user to fetch the created resource and then alter it as needed (via 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>