Treating collections as a resource

I’m submitting a

• bug report.
• feature request.

Current Behaviour:

I’ve been speculating for some time now that our treatment of collections as a single resource for every class is wrong. Nowhere in the spec is it mentioned that a collection is a set of all objects for a given class. It is mentioned that a collection is “a set of somehow related resources”. This does not imply that a collection would be only limited to class types

Expected Behaviour:

I think the direction we must move in is for users to be able to define collections on their own. Each collection itself would have an @id since it is a subclass of hydra:Resource. We then use the collection endpoint to relate classes/properties.

We use Collections directly instead of having pseudo-Collections defined by parent_id or child_id. The main problem with both the above approaches is as you mentioned, identifying the property which contains the parent/child id. This is because schema.org/identifier or hydra:Link and even https://schema.org/ItemList are general definitions that can be used for any property and need not necessarily be for only parent/child ids. The advantage of using a collection is that we define a CommentCollection object, where we link all Comment objects for a particular issue. We then give that CommentCollection object as the property for the Issue. In terms of defining it in the API documentation, it would be something like:

{
        "@type": "SupportedProperty",
        "property": vocab:CommentCollection,
        "readonly": "false",
        "required": "true",
        "title": "Comments",
        "writeonly": "false"
}

The property would map to an instance of the CommanCollection class. This will be defined in the supportedProperty field for the definition of the Issue class. Like any other object, when we define the Issue object, we will add the appropriate instance of the CommandCollection to the Issue instance. So an object would be something like:

{
        "@type": "Issue",
        "@id": "/api/Issues/27",
        "Issue": "....",
        "Comments": "/api/CommentCollection/32",
        ....
}

And then /api/CommentCollection/32 would have:

{
        "@type": "CommentCollection",
        "@id": "/api/CommentCollection/32",
        "members": [
                {
                        "@id": "/api/Comment/12",
                        "@type": "Comment"
                },
                {
                        "@id": "/api/Comment/18",
                        "@type": "Comment"
                },
                {
                        "@id": "/api/Comment/22",
                        "@type": "Comment"
                }
        ]

}

All this is part of the bigger implementation of treating collections as a resource. We allow hydrus to implement all operations: GET, PUT, POST, DELETE on all resource endpoints as well as on all collection endpoints. We then let users decide how they design their APIs and wether creation of resources happens at the collection endpoint or the resource endpoint is defined in the API Documentation itself. Nested collection would then be added to an object as any other resource.

NOTE: We should also allow the creation of both resources(Comment) as well as collections(CommentCollection) on the collection endpoint. We let the user decide which they want to use based on the API documentation. If the doc contains a supportedOperation to allow creation of resource using the collection endpoint then we create resources using that. Similarly for the case of resources. Hope this is clear.

[vddesai1871]

I think the direction we must move in is for users to be able to define collections on their own.

👍

The main problem with both the above approaches is as you mentioned, identifying the property which contains the parent/child id. This is because schema.org/identifier or hydra:Link and even https://schema.org/ItemList are general definitions that can be used for any property and need not necessarily be for only parent/child ids.

I think this problem can be solved by hydra:Link, by having a ‘bidirectional’ link, as Markus has used here http://www.markus-lanthaler.com/hydra/api-demo/vocab. The solution you proposed is somewhat better than such reliance on links to imply relations, but still I think we will need to have that as fallback or alternative. As we are allowing the Api Designer to decide whether he wants to add new resources from the item resource endpoint or collection resource endpoint, if he chooses the collection endpoint then everything will work fine and we would be able to know whether newly added object belongs to some nested collection of other item resource or not( ex. If new comment is added on api/CommentCollection/3 then we know that the issue (or anyother class) which has this collection object(with id 3) is the parent of this new comment(basically this comment belong to that issue)) But if API designer allows addition on the resource endpoint (Comment/id) then how do we find out which issue this comment belongs to? Then only way for him to accomodate such parent child relation would be to have another link from child to the parent object. So the newly added comment will have a link to the parent issue.

[chrizandr]

Yes, I think we can close this