"collection" and "item" usage

[handrews]

This addresses #295. Note that both media types referenced in the
"collection" and "item" RFC as examples of use similarly define
create-on-POST semantics. This is the one aspect of the typical
HTTP Uniform Interface that is not identifiable purely from HTTP
method semantics, since POST, in general, can do anything.

Add a section on the IANA-registered "collection" and "item"
link relations. Describe the common create-via-collection
pattern. While colleciton resources described with these
link relations are not required to implement such creation
semantics, they are forbidden from implementing incompatible
behavior when used with protocols such as HTTP where the pattern
is well-established.

Note, of course, that extended link relation types may be defined
to identify collections with non-standard behavior in a Hyper-Schema
context.

[dlax]

Nice addition.

Perhaps the introduction of could be less abrupt, but I guess it'd be easier when the whole document organization will get reworked (# 377), so this is fine for now.

[dlax]

typo: the link

[handrews]

Thanks, fixed.

And yes, this is less abrupt in the reworked version, which I've been poking at.

[dlax]

What do you mean by "identical" here?
For instance, if I'd like to add constraints on the submissionSchema (like a required or the "readOnly": true from the example below, assuming it's not already on /thing's schema), is this allowed?

[handrews]

This wasn't supposed to say "identical", actually. I just kept rewriting it, and then changing ti back, and apparently forgot I still needed to work on it. At various times it was "analogous to" or "compatible with".

What I want to convey is that the representation used to create a resource here should be more-or-less the same as the one used in "targetSchema" for the individual resource's "self" link. But It can, of course, differ in things like the server-generated "id" being absent during creation but required in "targetSchema". I actually handle that by just marking it read-only and not required in the schema but documenting that it's always present when retrieved from the server.

I'm not sure how to explain exactly what should and shouldn't be allowed here. I don't even want there to be some hard and fast rule, and it definitely needs to be a SHOULD or RECOMMENDED instead of a MUST.

Any suggestions welcome.

[handrews]

In the postamble of the example, I used "matching", but didn't explain what that meant either.

[dlax]

"compatible with" sounds good to me; what you meant is clear enough I think (I just ticked on "identical", but now that's fine) and follows common sense so that it probably does not need more explanation.

[dlax]

I'm not sure about this one. Maybe this about what is meant by "resource creation".

Typically, I'm thinking about using the collection+item pattern to describe relationships. For instance, consider a Article tags Tag relationship model, POST-ing to the URI some article's tags relationship (something like /articles/1/tags/) may lead to different results depending on the payload and server semantics: it could set a relation between the article and an existing tag (identified by payload) without modifying the underlying entities, or it could add a new tag entity with a relation set. The latter case arguably falls into "resource creation" semantics, but it's not obvious for the former, though one could argue that a new relation is created.

Also, what about a PUT or a DELETE request? Should we specify the expected behavior as well?

In fact, I wonder if we shouldn't discuss this "protocol semantics" topic separately and let this PR focus on documenting the pattern (where each link should be, how to set the context with anchorPointer).

[handrews]

@dlax There is no concern with PUT and DELETE, whose semantics are clear.

The problem here is that creating a resource with a server-assigned identifier is not part of HTTP's uniform interface. But it is one of the most common operations that is done in APIs, and it is flatly impossible to write a generic hypermedia client without it.

Take a look at application/collection+json and application/maze+xml, which are both given as the examples of use of "collection" and "item" RFC. Both of these specify creation-via-POST semantics for collections based on these link relations.

For your tag example, there is nothing problematic about any of those behaviors. The resource has to define what it means to be created. The point is not to tie "resource creation" to "put a thing in a database", or any other implementation. Both of the options you give are implementation details. The point is to ensure that if this exact relation is used, that POSTing to such a resource doesn't do something totally unexpected and damaging, like reboot the application. Which would otherwise be a completely valid thing for a resource to do in response to a POST (because literally anything is valid for POST).

[handrews]

This doesn't even say that creation has to be supported. It just says not to completely break clients that need SOME generic clue as to how to accomplish this. Link relation types are the only correct way to specify semantics.

And to be clear, these are link/resource semantics, NOT protocol semantics. That's kind of the entire point- there is nothing in HTTP that officially carries these semantics. Nothing we do in this media type changes that.

But per RFC 5988bis:

Link relation types can also be used to indicate that the target resource has particular attributes, or exhibits particular behaviours

We are following existing patterns, referenced in the RFC that defines these link relation types, to constrain behavior in order to make it possible to implement a generic hypermedia client using JSON Hyper-Schema.

[dlax]

@handrews I've thinking about this a bit more...

I think that what made me worry is that the text about "resource creation and POST" is located at the very beginning of the section whereas I would have expected to first read about how to use the collection+item pattern in a JSON Hyper Schema document. (In fact, I'm not that worried and the example I posted was mostly rhetorical.)

So I was about to suggest to move this part (starting from "A well-known design pattern..." to where this comment is attached) later in the section, but I'm actually not sure if it'd make still sense. So if it doesn't, I can live with it as is :)

[handrews]

@dlax yeah, that's fair, and I think I can get it to introduce the creation pattern less abruptly. If it's OK with you I'll just note that for the rewrite, as I'll almost certainly be reworking the text anyway.

[dlax]

If it's OK with you I'll just note that for the rewrite, as I'll almost certainly be reworking the text anyway.

Sure, that works too.

[handrews]

This will not be split, because the entire point of the section is to define this. The positioning of anchorPointer on its own is not worth putting in the spec. It follows from the collection/item RFC and the definition of anchorPointer.

[handrews]

@dlax I am really glad you are asking these questions. I know I push back hard with some of my answers, including these, but if you find it unclear (after spending a great deal of time with the project), then others will as well.

If there's a way we can make the purpose of the section more clear so that others don't find it confusing, that would be great. I want to clarify the roles of link relations vs protocols vs media types. I think that #377 will help this by describing the usage of rel and specific relation values in the overall context of the 5988bis model.

[handrews]

This last push was just a rebase/conflict resolution prior to merging, with no changes to the contents.