CODEWITHSUNDEEP
apirestrestful-architecture
Vivin Paliath
Vivin Paliath

Reputation: 95518

RESTful way of referencing other resources in the request body

Let's assume that I have a resource called group with the following representation:

{
    "id": 1,
    "name": "Superheroes"
    "_links": {
        "self": {
            "href": "http://my.api.com/groups/1"
        }
    }
}

Now let's say I want to create a new person instance by POSTing to /persons/1. Which of the following should I use for the request body:

Using ID

{
    "name": "Batman",
    "groupId": 1
}

Using link

{
    "name": "Batman",
    "group": "http://my.api.com/groups/1"
}

With the first method I access the id directly either to look up the related resource or eventually store the id in the database, when I persist the person instance. But with the other method, I either have to extract the id from the URI or, follow the link to load the related resource, and then find out its id. I really don't want to store the URI in the database.

With the latter option, seeing that the server controls the structure of the URI, is it fine for me to parse the id out of the link? Following the link back to the server itself seems odd, seeing that at this point we already have access to the information directly (we just need the id).

So to sum up, which of these options is best?

Upvotes: 1

Views: 1174

Answers (3)

Marcel Krcah
Marcel Krcah

Reputation: 622

TL;DR: Use simple ids.

More detailed explanation:

A straightforward approach is to create a person by POSTing to /groups/1/persons with a payload {"name": "Batman"}.

However, while such approach works for simple cases, the situation gets complicated if there are 2 resources that need to be referenced. Let's assume that a person also needs to belong to exactly one company:

GET /persons/1
{
   "name": "Batman",
   "group": 1,    // Superheros, available at /groups/1
   "company": 5  // Wayne Enterprises, available at /companies/5
}

Since there is no relationship between companies and groups, it is not semantically correct to create a person via POSTing to /groups/1/companies/5/persons or to /companies/5/groups/1/persons.

So let's assume you want to create a person with a request looking like this:

POST /persons
{
    "name": "Batman"
    "group": ???,     // <--- What to put here?
    "company": ???    // <--- What to put here?
}

Which brings us to the answer to your question:

Ease of use. Your API should be primarily designed for the ease of use. This is especially true, if you design a public API. Therefore, Option 2 (Use the link, but parse out the id) is out, since it imposes additional work for clients of your API.

Constructing search queries. If you want to be able to query persons which belong to the company 10 and the group 42, simple ids lead to more readable and less error-prone urls. Which of the following do you consider more readable?

  • URL with a simple id:

    GET /groups/42?company=10

  • or URL with a url-encoded link:

    GET /groups/42?company=http%3A%2F%2Fmy.api.com%2Fcompanies%2F10

I wouldn't underestimate the point of readability. How many times do you need to debug your API in various curls, logs, postmans, etc.

Development Links need to be parsed in the backend, while simple ids can be used directly. It's not about performance, but rather about additional work/tests you have to put in.

Endpoint maintenance. Imagine that your API endpoint evolves. You decide one day to switch to https or to include versioning in the url. This might break API clients, if they for some reason rely on structure of the links. Also, you might want to checkout if link parsing on your backend is done properly.

Argumentum ab auctoritate I know this is not a proper argument, but if you checkout APIs of large players, e.g. Twitter, Github or Stripe, they all use simple ids.

HATEOAS. One common argument in favour of links is that it is aligned with HATEOAS. However, as far as I know, this relates to additional links in API responses rather than using links in payloads of POST requests.

All in all, I would go for simple ids, since I haven't yet heard a compelling argument favouring links, which would beat the aforementioned.

Upvotes: 2

inf3rno
inf3rno

Reputation: 26129

You are missing two important things here.

  1. You need a standard way to describe forms in the response, in this case your POST form.
  2. The information about the group ids / uris, or how to get them has to be described in the form in a standard way.

For example a HTML FORM with a SELECT INPUT would be RESTful. The closest thing we got in json to do the same is json-ld and hydra. But if you are obsessed with hal, then use hyperagent forms or something like that. It will never be a standard, but if compatibility is not an issue, then it is good enough.

To answer your question, you should use the id, because the server knows how to interpret it. The client needs the resource identifiers, the server needs it only in the uri part of the request, not in the body.

Upvotes: 1

weeksling
weeksling

Reputation: 11

From my experience, it is always best to go with the simplest solution for making requests.

The process of generating a new url and parsing it seems excessive to get a resource, whereas sending the id of the item you want seems much simpler.

Thus, I would send a request in the form:

{ "name": "Batman", "group": 1 }

Upvotes: 1

Related Questions