Best practices for POSTing nested objects to REST server

Question

I'm wondering what is the usual approach when developing REST API servers for creating or updating nested data.

Suppose I have a set of database models as follows:

"client" (id, firstname, lastname, ForeignKey to "address")
"address" (id, street, city, state, country)
"email" (id, type, emailaddress, ForeignKey to "client")
"phone" (id, type, number, ForeignKey to "client")

In other words a client has a single address, but there can be multiple emails per client and multiple phone numbers per client. Now suppose that I am developing a REST API server that allows users to create/edit/delete any of these objects. The "address" and "email" and "phone" objects are straightforward. However, what about "client"? When a user wants to create a new client, that user would send a POST command to the server with a data structure in JSON that would look something like this:

{
    "id": 123,
    "firstname": "John",
    "lastname": "Smith",
    "address": {"street": "123 Anystreet", "city": "Los Angeles", "state": "California", "country": "USA"},
    "emails": [
        {"id": 7, "client_id": 123, "type": "home", "emailaddress": "[email protected]"},
        {"id": 12, "client_id": 123, "type": "work", "emailaddress": "[email protected]"}
    ],
    "phones": [
        {"id": 28, "client_id": 123, "type": "home", "number": "(555) 555-1234"},
        {"id": 17, "client_id": 123, "type": "work", "number": "(555) 555-9876"}
    ]
}

So what should the REST server do with this information? Obviously it should save the top level client object (with the firstname and lastname fields) but what should it do with the nested objects? Should it check the database for say email with id=7 and update that email object? Or should it check the database to set ONLY email with id=7 or id=12 to point to this client? It isn't clear to me what are the expected semantics of nested REST object create and update operations. Or is it/should it be the case that REST create/update operations should only be performed on the top level object, and if a user wants to create or modify the nested/embedded objects then the user should make additional REST calls to do so?

Answer 1

So what should the REST server do with this information?

It should pass the message to the component that knows how to create the client, or more generally, it should

process the representation enclosed in the request according to the resource's own specific semantics.

See RFC 7231

is it/should it be the case that REST create/update operations should only be performed on the top level object

No, don't make it hard. REST isn't about objects, or entities in your data store. We're just manipulating resources; in this case, we're just delivering a request that says "please create a client". So create a client that matches the description in the message; and report on that result. Or, if there is an error in the request, then send back a message explaining the error.

The fact that creating this resource in turn requires creating an entity in a database, or creating relationships between this entity and other entities in your database, is an implementation detail that is of no interest to REST.

The goal, remember, is to make your server act like it's just a website full of documents.