Json-api: Sideposting: graph requirements and restrictions

[ethanresnick]

This is another splinter issue from #1197 to discuss a few independent checklist questions. The result of this discussion can then be used to update the checklist in #1197. The items for this issue:

• [x] Should we put restrictions on the kinds of graphs allowed or should we leave it to the server implementations? Resolution: Yes, only graphs that satisfy the full linkage requirement are allowed.
  
  
  
  • [ ] Should we put minimum requirements of the kind of graphs a server must support?
  
  

My current thinking is:

• I'm fine saying that the server is allowed to support any graphs it wants (i.e., no restrictions). However, as I mentioned here, that probably means we have to create another exception to the full-linkage requirement to allow the case where there's a resource in included that's not connected to the primary resource or any other included resource (i.e., it's really just specifying a second, independent creation).

• I do think we should require, at a minimum, that implementations support graphs in which the only temporary resource identifier objects point from the primary data to sideposted resources. (That is, graphs where the included resources don't link to one another and are connected to the primary data.) A server that didn't support this simple case seems like it would be borderline useless.

[brainwipe]

I think the only restriction on the graph is that there is full linkage. The client can keep track of tid and build complex graphs pertaining to a single resource.

The reason is that you are minimising the amount of domain that is being leaked outside of the API. Creating a complex hierarchy on the client side and posting as a single resource is one thing but to build any arbitrary resources on the client and throw them at the server to sort out isn't much of a specification.

If you don't restrict to a single resource then you're saying that the endpoint can accept batch or any combination or resources regardless of how they are joined. If that's what the client needs then a REST service is no longer appropriate.

[beauby]

I second @brainwipe in that dropping the full linkage requirement opens the door to highly unstructured APIs (namely a single /god endpoint that allows pretty much anything).

[ethanresnick]

Ok, you've both persuaded me; let's keep the full linkage requirement. I've updated the OP accordingly.

What do you think about minimum support requirements (the second bullet)?

Also, @dgeb any thoughts on this issue (or sideposting in general)? I want to make sure to get your input to flag/catch any issues before the details of this proposal get too far along.

[beauby]

Regarding the minimum support requirement, I think servers will usually have some kind of authorization mechanism (like you're allowed to create a new user, along with a few shipping_addresses, but you're not allowed to sidepost any evaluation for the user). I'd be in favor of a clearly stated behavior to signify the client that "this sideposting request is not allowed".

[brainwipe]

implementations support graphs in which the only temporary resource identifier objects point from the primary data to sideposted resources

Completely agree. If you sidepost to other primary resources, you're doing batch/loose graphs by the backdoor.

[beauby]

@brainwipe I believe @ethanresnick's comment you're referring to was actually about setting minimal graph supports, rather than limiting graph complexity.

[brainwipe]

Ah, thank you...

As long as you have full linkage, I don't think a minimum requirement is needed beyond the existing spec of a single resources and no children. The graph doesn't _have to be_ a strict tree or unidirectional directed structure as a minimum, as long as there is full linkage.

Error reporting using HTTP status codes and a meta tag is going to be very important for the client developer but that is implicit in the design of any API.

[beauby]

I agree with @brainwipe regarding the fact that full linkage should be the only requirement.

A server that didn't support this simple case seems like it would be borderline useless. @ethanresnick

Well such a server would be implementing the current spec, no?

[ethanresnick]

I'd be in favor of a clearly stated behavior to signify the client that "this sideposting request is not allowed".

Yeah, I definitely want that too. I think that falls under a different checklist item from #1197, namely: "Should we offer further guidance on responding to unsupported sideposting requests? (Unsupported graph, etc.)". I didn't include that question here because I think it's still blocked on #1199, which I'm gonna try to get back to really soon. But yeah, I agree with you.

For minimum support requirements, it sounds like we're implicitly saying there shouldn't be any, which I guess I'm fine with.

[brainwipe]

For minimum support requirements, it sounds like we're implicitly saying there shouldn't be any, which I guess I'm fine with.

That sounds a little harsh. I think we _do_ already have a minimum requirement: a single resource and full linkage. That's a really solid minimum requirement. ;)

[beauby]

@brainwipe I think by "minimum support requirements" @ethanresnick meant server-side requirements, i.e. "state that servers have to support some simple graphs, such as trees of height 1". My take, again, is that this should be left to server implementation.

[beauby]

If we all agree that

1. client-side restrictions are full-linkage only (plus the existing restriction that there should be at least one resource with type among those represented by the endpoint)

A server MUST return 409 Conflict when processing a POST request in which the resource object’s type is not among the type(s) that constitute the collection represented by the endpoint.

1. there are no server-side restrictions

I believe we should close this issue, and open a new one discussing the guidance for responding to unsupported sideposting requests.

[beauby]

ping @ethanresnick

[ethanresnick]

Sorry for slow response. Been busy and have been mulling this over a bit. I think my feelings depend on how rigorously we keep the separation between primary and sideposted resources (see my latest comment in https://github.com/json-api/json-api/issues/1215#issuecomment-329921879 about that). If we blur the two together, then I agree with what your proposal. If primary and sideposted remain conceptually separate, though, I think I would still want to require that a server that supports a complex case (e.g., the linking from sideposted to primary shown below) to also support the most-common/basic case of linking from primary to sideposed.

I.e., servers (or server libraries) supporting:

POST /articles
{
  "data": {
    "type": "articles",
    "tempid": "1",
    "attributes": { /* .... */ }
  },
  "sideposted": [{
     "type": "people",
     "relationships": { 
       "firstArticle": { 
       "data": { "tempid": "1" } 
     }
  }]
}

should also be able to support:

POST /articles
{
  "data": {
    "type": "articles",
    "relationships": { 
      "author": { "data": { "tempid": "1" } }
    }
  },
  "sideposted": [{
     "type": "people",
     "tempid": "1",
     "attributes": { /* ... */ }
  }]
}

This requirement would say to server library authors: if you want the "you are compliant" stamp of approval, and you're gonna support some sideposting, you have to support the basic case. Hopefully, that would stimulate more support for the sideposting most people care about, and give people arguing that a library should add such support a bit of ammunition (they could point to the spec and say "see, this is required").

This requirement would have to be written in a way that makes it clear that a particular API can choose not to support a particular graph at a particular endpoint if supporting that graph would violate one of its business rules. (This is analogous to how the requirement that a relationship link must support updating a relationship is not taken to mean that an API must allow such updates even if the user doesn't have permission to perform them—even though we never state that exception explicitly.) I'm not trying to impinge on individual APIs here, so much as raise the general level of support clients can expect, like with sparse fieldsets.