Search code examples
restapi-designhateoas

Updating HATEOAS rels

Let's say I'm shooting for a HATEOAS-compliant API. I provide the endpoint /cars/{id}. If a user were to call GET /cars/12, they'd see something like:

{
    "color": "Red",
    [...],
    "links": [
        { "rel": "driver", "href": "/people/123" },
        { "rel": "owner", "href": "/people/456" },
    ]
}

In this model, how do I update a relationship? Like, say the car gets sold to /people/42. Does the PUT change the value of the owner href?

Solution

  • There are a lot of possibilities to do this. This API does not need to be one-to-one data representation, so with that it mind:

    • You can modify the resource using PUT, even the links if you want
    • You can expose a separate "owner" resource for the car, and PUT a new owner there
    • You could expose an "owned cars" resource from people, and POST to that collection, which causes the car to change owners

    It depends on how the system is distributed, it may be the case that not all resources are under your control. People could be federated links to third-party resources, in which case they might not have links back to your system, etc.

    If everything is under your control, all of the options are possible.