Resource objects: links vs. relationships

1

In this question I’m referring specifically to resource objects:
http://jsonapi.org/format/#document-resource-objects.

How do I decide whether to use a links or relationships?

I understand that relationships provides features that links does not, such as changing the author of an article by issuing a DELETE/POST to the article’s author relationship.

In my use-case I do not need to explicitly reference or alter the relationship, I only need to provide the link to the related resource, but I’m curious if I should use the relationships object anyway.

Example:
I have a typical json:api resource, and I want to provide a POST only sub-resource.

resource: GET|POST /projects
sub-resource: POST /projects/1/workflow-transition

Note that I’ve rejected the approach of using PUT /projects to make the data changes involved in the workflow transition, because it would require the client app to understand too much server-side business logic.

In Relation Link Usage @ethanresnick says
"[The related link is] designed primarily for GET, though I think the spec would also allow a POST to it."
So at least it may be allowed to use relationships like so:

{
  "type": "projects",
  "id": "1",
  "attributes": {...},
  "relationships": {
    "workflow-transition": {
       "links": {
         // client issues a POST to this URL
         "related": "/projects/1/workflow-transition"
       }
    }
  }
}

However since I don’t really need to model the relationship between a project and its workflow-transition, it seems simpler to use a links object instead.

{
  "type": "projects",
  "id": "1",
  "attributes": {...},
  "links": {
    "workflow-transition": "/projects/1/workflow-transition"
  }
}

Are there reasons to use one or the other approach?

2

The spec doesn’t allow you to define your own keys inside links, you can only use the pre-defined keys: self, related, first, last, prev, and next (and some of these are only valid in certain parts of the response)

3

@jlangley the restrictions you mentioned about the links member sound like Top Level Links.

http://jsonapi.org/format/#document-top-level

The top-level links object MAY contain the following members:

  • self: the link that generated the current response document.
  • related: a related resource link when the primary data represents a resource relationship.
  • pagination links for the primary data.

I’m referring to the links member of a resource object.
http://jsonapi.org/format/#document-links
There the spec it does not seem to specify a restricted set of link relation names. It’s hard to tell though because the examples do use self and related.

If you can point me to any part of the spec that prohibits arbitrary link relation names in a non-top-level links member, or a rationale for that restriction, it would be great to know.

If such a restriction exists then the links member seems quite limited:

  • The only clear options are self or related
  • The meaning of related for a given resource object is ambiguous.
  • It’s debatable whether pagination links make sense within a resource object.
4

JSON:API — Latest Specification (v1.1) and Links Object Clarification Needed

The relationship is given meaning is given by the name of the relationship (e.g. author or comments in the example on the spec home page). The “related” link points to the related resource; the self link points to the “join” between the current resource and the related resource (similar to a foreign key in database terms).

They don’t, they’re for use in collections

5

Thanks for the answers! One nitpick about this part though:

The relationship is given meaning is given by the name of the relationship (e.g. author or comments in the example on the spec home page). The “related” link points to the related resource; the self link points to the “join” between the current resource and the related resource (similar to a foreign key in database terms).

I’m not talking about links within the relationships member. I understand that within a given relationship object, e.g. the comments relationship of an article, the related link refers to the comments. But what about the plain links member of a resource object? JSON:API — Latest Specification (v1.1)

By the rest of your answer I’m convinced that it can only have self and related, but it’s not clear what related should reference. It appears that it’s arbitrary and understood by my app domain.

6

Not both, only self: JSON:API — Latest Specification (v1.1)

7

Got it. I was interpreting “MAY contain a self link” as “self is an allowed link relation, in addition to potential others.” But the alternative interpretation of “a self link is the only relation it may have” makes sense.

Resource Links

The optional links member within each resource object contains links related to the resource.

If present, this links object MAY contain a self link that identifies the resource represented by the resource object.