# Resource objects: links vs. relationships

**URL:** <https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774>\
**Category:** Uncategorized\
**Created:** [October 3, 2016, 10:25pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774 "2016-10-03T22:25:29Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![skarger](https://avatars.discourse-cdn.com/v4/letter/s/45deac/32.png) [@skarger](https://discuss.jsonapi.org/u/skarger)\
**Post date:** [October 3, 2016, 10:25pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774/1 "2016-10-03T22:25:29Z")

</div>

In this question I’m referring specifically to resource objects:  
[http://jsonapi.org/format/#document-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](http://discuss.jsonapi.org/t/relation-link-usage/149/2) @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:

```auto
{
  "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.

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

```

Are there reasons to use one or the other approach?

---

<div class="post-metadata">

**Author:** ![jlangley](https://avatars.discourse-cdn.com/v4/letter/j/9e8a1a/32.png) [@jlangley](https://discuss.jsonapi.org/u/jlangley)\
**Post date:** [October 3, 2016, 10:45pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774/2 "2016-10-03T22:45:22Z")

</div>

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)

---

<div class="post-metadata">

**Author:** ![skarger](https://avatars.discourse-cdn.com/v4/letter/s/45deac/32.png) [@skarger](https://discuss.jsonapi.org/u/skarger)\
**Post date:** [October 4, 2016, 2:05pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774/3 "2016-10-04T14:05:54Z")

</div>

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

[http://jsonapi.org/format/#document-top-level](http://jsonapi.org/format/#document-top-level)

> The top-level [links object](http://jsonapi.org/format/#document-links) MAY contain the following members:

> - self: the [link](http://jsonapi.org/format/#document-links) that generated the current response document.
> - related: a [related resource link](http://jsonapi.org/format/#document-resource-object-related-resource-links) when the primary data represents a resource relationship.
> - [pagination](http://jsonapi.org/format/#fetching-pagination) links for the primary data.

I’m referring to the `links` member of a _resource object_.  
[http://jsonapi.org/format/#document-links](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.

---

<div class="post-metadata">

**Author:** ![jlangley](https://avatars.discourse-cdn.com/v4/letter/j/9e8a1a/32.png) [@jlangley](https://discuss.jsonapi.org/u/jlangley)\
**Post date:** [October 4, 2016, 2:27pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774/4 "2016-10-04T14:27:00Z")

</div>

> [@skarger](#):
>
> 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.

[JSON:API — Latest Specification (v1.1)](http://jsonapi.org/format/#document-resource-object-links) and [Links Object Clarification Needed](http://discuss.jsonapi.org/t/links-object-clarification-needed/130)

> [@skarger](#):
>
> The meaning of related for a given resource object is ambiguous.

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).

> [@skarger](#):
>
> It’s debatable whether pagination links make sense within a resource object.

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

---

<div class="post-metadata">

**Author:** ![skarger](https://avatars.discourse-cdn.com/v4/letter/s/45deac/32.png) [@skarger](https://discuss.jsonapi.org/u/skarger)\
**Post date:** [October 4, 2016, 3:50pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774/5 "2016-10-04T15:50:50Z")

</div>

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)](http://jsonapi.org/format/#document-resource-objects)

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.

---

<div class="post-metadata">

**Author:** ![jlangley](https://avatars.discourse-cdn.com/v4/letter/j/9e8a1a/32.png) [@jlangley](https://discuss.jsonapi.org/u/jlangley)\
**Post date:** [October 4, 2016, 4:03pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774/6 "2016-10-04T16:03:03Z")

</div>

> [@skarger](#):
>
> By the rest of your answer I’m convinced that it can only have self and related

Not both, only `self`: [JSON:API — Latest Specification (v1.1)](http://jsonapi.org/format/#document-resource-object-links)

---

<div class="post-metadata">

**Author:** ![skarger](https://avatars.discourse-cdn.com/v4/letter/s/45deac/32.png) [@skarger](https://discuss.jsonapi.org/u/skarger)\
**Post date:** [October 4, 2016, 4:11pm UTC](https://discuss.jsonapi.org/t/resource-objects-links-vs-relationships/774/7 "2016-10-04T16:11:28Z")

</div>

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.