REST API update child reference

Question

I'm working on a project where we are creating some REST APIs

My question is when we are creating an API to update an entity that contains a children reference, i.e.

{
    name: '...',
    email: '...',
    country: {
        id: xxx,
        name: 'xxx'
    }
}

Does the update api accept a country object or just a country id. The country object will not be updated, only the reference to the country gets updated?

My preference is country id since we are not updating the country object, but my college think otherwise.

Answer 1

Why not just record the country_id only and internally figure out the id to name mapping? i.e.

{
    name: '...',
    email: '...',
    country_id: xxx
}

You can even use country_code instead of an internal id for reference. Less things for clients to pass in, less chance of messed-up data (e.g someone passing country id as US and country name as Canada).

In general, avoid passing redundant data. As your api develops, this adds up. It's also more data that you need to pass around, keep secure, validate and clean-up. One exception is that if all your clients always have the data in a certain format, then it'll make sense to make it easy for them to pass the data in whatever format/structure they all have and translate to your preference server side.

Answer 2

In a REST API you will work with resources.

A quote from Roy Fielding’s REST dissertation:

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

In your case you have a Client and a Country resource, and theres a relationship between them. But to avoid confusion - beetween Client API and Client Resource - let's change the resources to Order and Table.

You have to work with each one separatedly.

Operations in one resource URI operates in that resource alone.

/service/order/{id} //handles orders operations
/service/table/{id} //handles tables operations

Use Hypermedia as the engine of application state (HATEOAS)

A REST client enters a REST application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server. The media types used for these representations, and the link relations they may contain, are standardized. The client transitions through application states by selecting from the links within a representation or by manipulating the representation in other ways afforded by its media type. In this way, RESTful interaction is driven by hypermedia, rather than out-of-band information.

In your case we can get a cenario like this:

1) A API Client requests a Order resource.

GET /service/order/12345 HTTP/1.1
Host: restserviceurl.com
Accept: application/xml

2) The API responds.

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...

<?xml version="1.0"?>
<order>
  <id>12345</id>
  <description>An delicious hamburger ASAP</description>
  <link rel="table" href="https://service/table/6789" />
</order>

Note that the response contains a link. If the API Client wants to manipulate the Table resource it will follow the link to do any operation on that resource.

So if the API Client needs the Table of the Order Resource it will do an GET on that link.

With all that said, in your case you want to update the country of an client. All you have to do is change the id of the Country in the Client resource. Them do a POST to create a new Client resource or a PUT to modify an existing one in the Client API URI.

If you need to change the Country Resource do that on the other URI.