Link to another resource in a REST API: by its ID, or by its URL?

20.4k views Asked by At

I am creating some APIs using , so the language used is JSON.

Let's assume I need to represent this resource:

{
    "id" : 9,
    "name" : "test",
    "customer_id" : 12,
    "user_id" : 1,
    "store_id" : 3,
    "notes" : "Lorem ipsum example long text"
}

Is it correct to refer to other resources by their IDs (12, 1, 3), or I should specify the URL of these resources (i.e. /customers/12, /users/1, /stores/3)?

I am not using HATEOAS and I am a bit confused.

2

There are 2 answers

0
stakx - no longer contributing On BEST ANSWER

DO include absolute entity URIs in your responses (such as /customers/12 or even http://www.example.com/customers/12).

DO NOT include just an entity's ID (such as 12) in a response, because that way you're forcing clients to put together resource URIs themselves. In order to do that, they would need to have prior knowledge of what URIs there are, and you're losing control over the URI space on the server side.

(Having the client put together an URI is OK if the server instructs the client how, e.g. by sending a URI template along with the ID; but if it did that, it could just as well send the resulting URI.)

See also:

  • "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark)."
  • "A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs[.]"

Example:

Your original resource could be re-designed as follows:

{
  "type": "foobar",
  "id": "9",
  "links": {
    "self": "//example.com/foobars/9"
  },
  "cashier": {
    "type": "user",
    "id": "1",
    "links": {
      "self": "//example.com/users/1"
    }
  },
  "customer": {
    "type": "customer",
    "id": "12",
    "links": {
      "self": "//example.com/customers/12"
    }
  },
  "name" : "test",
  "notes" : "Lorem ipsum example long text",
  "store": {
    "type": "store",
    "id": "3",
    "links": {
      "self": "//example.com/stores/3"
    }
  }
}

A few things to note:

  • Each resource (the main object being transferred, but also sub-resources) has some self-descriptive meta-data attached to it, such as type, id, links.
  • Sub-resources can include partial or complete data. As long as the self-link is there, the client knows where to get the complete resource.
  • The type might seem somewhat redudant; often, you implicitly know what kind of object to expect. This property can help in validation, and also gives you the opportunity to distinguish between object type and role (e.g. cashier is-a user in the above example).
1
MeV On

I have had a look of other popular APIs (Facebook, Spotify) and I believe the following one is the best way to do it:

{
   "id" : 9,
   "name" : "test",
   "customer" : {
      "id": 12,
      "href": "/customers/12"
   },
   "user" : {
      "id": 1,
      "href": "/users/1"
   },
   "store" : {
      "id": 3,
      "href": "/stores/3"
   },
   "notes" : "Lorem ipsum example long text"
}