Control over relationship objects

1

From the docs:

For example, a GET request to an individual article could return:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "related": "http://example.com/articles/1/author"
        }
      }
    }
  }
}

Where does the relationships object come from. What triggered it to be there as it is optional? When to add it, when not. How make it clear what is going to happen to a client?

…and now, for something completely different, The trailing slash. Slash for collections, none for items.

There’s no mention in the spec, or didi I miss it. All examples are without, there where I expected them in various places.

So, not using the trailing slash I could imagine:
GET http://example.com/articles/1

{
  "links": {
    "self": "http://example.com/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    }
  }
}

and using one
GET http://example.com/articles/1/
I can imagine the result from the spect example. Adding a slash pushes the item towards collections, we treat it like so and fetch related data, author, publisher, magazine etc.

2

By default, you need all fields (attributes and relationships) in your payload, unless the client specified which ones it wants with the field parameter.

There is nothing in the specification about trailing slashes. I would suggest you ignore them when receiving requests and not add them when building links.

3

In the spec, section ‘resource objects’ it says: “In addition, a resource object MAY contain any of these top-level members:” relationships is one of the mays

4

After reading a little more the spec, maybe you’re allowed to decide not to have any field if the client do not specify anything through the field parameter. You would end up with only id and type. I’d like a second opinion on that.

That being said, it doesn’t change the fact that it can be there anytime if you want it to be there, unless the client specifies a list of fields that does not contain any relationship.

The spec says MAY because a resource might simply not have any relationship, or maybe the client did not ask for it.

5

As I read it, not including fields you return all data & attributes. Looking at whether a returned field has a relation to decide whether or not include relations is not explicit, nor is the spec. Then I’d expect wording like, if relations on returned fields exist they MUST be included …

regarding the trailing slash, I’ve been playing with it a bit and a nice pattern emerges:

/notebook                              -> subordinate, may redirect 301 "/" or 404
/notebook/                             -> (paginated) lists books
/notebook/{nb_id}                      -> as leaf, shows book data & attributes
/notebook/{nb_id}/                     -> as collection, shows book data, attributes and relations
/notebook/{nb_id}/note                 -> subordinate, may redirect 301 "/" or 404
/notebook/{nb_id}/note/                -> (paginated) list of notes
/notebook/{nb_id}/note/{n_id}          -> shows note data & attributes
/notebook/{nb_id}/note/{n_id}/         -> shows note data & attributes and relations
/notebook/{nb_id}/note/{n_id}/history  -> subordinate, may redirect 301 "/" or 404
/notebook/{nb_id}/note/{n_id}/history/ -> (paginated) list of historic versions
6

I don’t understand that sentence. Could you rephrase it? What is a returned field? What returns it? What do you mean by “include relations”? You probably mean “relationships”, which is the term used in the specification.

For the trailing slash, I wouldn’t use it. It’s not mentioned by the spec. Maybe technically it’s legal, but it would always feel hacky from a JSON:API point of view. Clients designed to read JSON:API endpoints would not know how to handle them.

By the way, why nested resources like /notebook/{nb_id}/note/{n_id}? Why not just /note/{n_id}? With the first option, you are introducing more unnecessary logic and weird cases.

(friendly note: Your topic has two subjects (relationships and trailing slash) and it is confusing. Next time, write two topics.)

7

“If an attribute in a resultset has a relationship, relationships should be included (for that attribute) in the resultset” is not explicit (from the GET link) nor is it explicitly stated in the spec. Meaning, GET /article/1 does not tell me wether there will be relationships included, if any available. I tried to make this explicit by using the trailings slash and it seems to work.

Regarding the slash, although RFC3986 is noted a few times in the spec it does indeed not say that links should adhere to RFC3986, the examples look like they don’t (GET /articles/1?include=comments). If it doesn’t follow RFC3986 then it should be exactly specified what to follow. Not following RFC3986 would be rather strange though.

/notebook/{nb_id}/note/{n_id} Nested resources as notes have no notion of the notebook they belong too. In the bigger application they can belong to multiple ones and there are different book types beside notebooks. Just a thingy to fiddle with at the moment.