REST and automatic creation of related resource

Question

I am learning REST principles and I have a doubt on working with complex resources.

Let's say we have two resources, Foo and Bar, and for every Foo I must have a Bar. I want to make the dependency of bar from foo clear to developers using my API, so:

1) I will use links from Foo instances to Bar instances, and viceversa

GET /foos/1
Foo: {
    'name': 'Foo instance',
    'rel_bar': '/foos/1/bar'
}


GET /foos/1/bar
Bar: {
    'name': 'Bar instance',
    'rel_foo': '/foos/1',
}

2) I will use a URI templating that shows the dependency from Foo towards Bar (this is just for humans, as URI should be opaque for REST).

/foos               --> Foo resource collection
/foos/{foo_id}      --> An instance of a Foo resource
/foos/{foo_id}/bar  --> The bar instance associated to the foo instance foo_id

So again, there are not bar without a corresponding foo.

Now I wish to create a Foo resource.

POST /foos
{
   'name': 'Yet again another foo instance',
}

And let the server to create the corresponding Bar default (or empty) resource, so the next read will give:

GET /foos/2
{
   'name': 'Yet again another foo instance',
   'rel_bar': '/foos/2/bar'
}

And...

GET /foos/2/bar
{
   'name': null,  --> Let's say that null is the default value.
   'rel_foo': '/foos/2/bar'
}

Is 'RESTfully correct' do this? My concerns are:

1. is correct to let the server to automatically create a related resource? Or should I split the creation of Bar and Foo in two steps?
2. is correct to POST a representation (just the 'name' attribute) and GET back a different one ('name' and the assigned 'rel_foo').

My personal thought is that since Bar has no meaning without a Foo, probably yes, I should let the server to create it.

Any idea?

Answer 1

I am not sure if what you describe are independent resources Foo and Bar. You say:

for every Foo I must have a Bar

Together with the 'JSON' and the URIs your describe, I would call this a sub-resource relation: For every Foo there must be one and only one Bar which can not exist outside this Foo.

If this interpretation is correct, I would keep your URIs but change the represenation to this:

GET /foos/1

{
    'name': 'Foo instance',
    'Bar': {
        'name': 'Bar instance'
    }
}

Notice that I didn't include the rel_bar and the rel_bar which are not necessary.

You can GET only the Bar sub-resrouce:

GET /foos/1/bar

{
    'name': 'Bar instance'
}

Notice that in this represenatation there is no link element back to the parent Foo. Such a link is unnecessary since the URI makes the resource/sub-resource relation clear.

Your questions 1:

is correct to let the server to automatically create a related resource? Or should I split the creation of Bar and Foo in two steps?

It is not important if a bar sub-resource is actually created in some backend. What matters is that it is reachable as a member of a representation of Foo. After only POSTing a Foo represenation, the represenation of the Bar sub-resource will have default values as you describe. It could be overriden later:

PUT /foos/1/bar

{
    'name': 'A name for this Bar'
}

Your questions 2:

is correct to POST a representation (just the 'name' attribute) and GET back a different one ('name' and the assigned 'rel_foo').

Yes, that is correct. The client can POST or PUT a represenation that is incomplete. The important thing is to always handle such incomplete represenations in a consistent way. I find it totally agreeable that a Bar sub-resource is created for each new Foo.