Link to another resource in the REST API: by its identifier or by its URL?

Question

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

Suppose I need to submit this resource:

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

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

I do not use HATEOAS and I am a bit confused.

Answer 1

DO include / customers / 12 or even http://www.example.com/customers/12 ).

It does NOT include only the identifier of the object (for example, 12 ) in the response, because in this way you force clients to collect their own resource URIs. To do this, they will need to know what URIs are, and you lose control of the server-side URI space.

(If there is a client, the URI is fine, if the server instructs the client, for example, sending the URI along with the identifier, but if he did, he could just send the received URI.)

See also:

• The article "REST API must be processed with hypertext" by Roy T. Fielding (creator of REST). Pay particular attention to these two points:

  • "The REST API must be entered without prior knowledge outside the original URI (bookmark)."
  • "The REST API should not define fixed resource names or hierarchies (obvious client-server interactions). Servers should have the freedom to manage their own namespace. Instead, allow servers to tell clients how to create the appropriate URIs [.]"

• HAL , which specifies a standard way to put links to related resources in your responses.

• JSON API - "specification for creating API in JSON"

• The above tips apply not only to identifiers of other resources (for example, "foreign keys" such as your customer_id ); You would also turn your own id resource into a so-called "personal link"; see SO question "What is the importance of a native link in the hypermedia API?" .

Example:

Your source resource can be redesigned 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 notes:

• Each resource (the main object that is transferred, but also sub-resources) has some self-describing metadata attached to it, such as type , id , links .
• Sub-resources may include partial or complete data. As long as there is a relationship, the client knows where to get the full resource.
• type may seem somewhat redundant; often you implicitly know which object to expect. This property can help in checking, and also makes it possible to distinguish between the type of object and the role (for example, cashier is-a user in the above example).

Answer 2

I had other popular APIs (Facebook, Spotify), and I believe the following method is the best way:

 { "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" } 

Any comments?