Specify / give example of what a 'list space contents' request looks like

[dmitrizagidulin]

Currently, we have an example of what listing a collection looks like (the response JSON has an items property, AS2 style):

Example response from GET /space/{space_id}/{collection_id}/:

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "73WakrfVbNJBaAmhQtEeDv",
  "name": "Verifiable Credentials Collection",
  "type": ["Collection"],
  "totalItems": 0,
  "items": []
}

Now, need to specify several additional things:

1. What does each item in the items array look like? (when referring to any sort of resource, files, PDFs, json objects, etc)
2. Add an example of how to list the contents of the "default"/root space collection. (That is, how do you list the contents of a space).

[dmitrizagidulin]

Added an initial PR (#25) with straw example of what the contents of a space look like in a response. (This is also something to be decided for collections as well)

Option 0 - Current Approach

Outlined in PR #25.

The main downside to this approach is - if you do a GET to a space URL, and you always get back both the space properties (name, id, controller, etc) AND the contents of it, this does not allow those two things to be addressed separately.

(in RDBMS terms, this is the difference between DESCRIBE <table> and SELECT * from <table>)

Alternate Option 1 - Use the trailing / to switch between space/collection meta and its contents

Meaning, example.com/space/{space_id} would return the space description object (with id, controller, name, etc) with no items

but example.com/space/{space_id}/ (WITH the trailing slash) would return only the representation of the list of contents (AS2 Collection style, etc).

Benefit of option 1: clients can deterministically get the contents of a space or collection, just by knowing its id.
Downside: might be too subtle (/ vs no /). Plus, suffixes bring their own downstream challenges.

Alternate Option 2 - Specify a contents suffix

Meaning, example.com/space/{space_id} would return the space description object (with id, controller, name, etc) with no items

and example.com/space/{space_id}/contents would return only the representation of the list of contents of the space's default collection (AS2 Collection style, etc).

Benefit of option 2: clients can deterministically get the contents of a space or collection, just by knowing its id.
Downside: Suffixes bring their own downstream challenges.

Alternate Option 3 - Add a contents link to spaces and collections

So, example.com/space/{space_id} (with or without trailing /) would always return the space (or collection) description object, but it would include a new property, e.g.:

{
  "id": "81246131-69a4-45ab-9bff-9c946b59cf2e",
  "type": ["Space"],
  "name": "Example space #1",
  "controller": "did:key:z6MkpBMbMaRSv5nsgifRAwEKvHHoiKDMhiAHShTFNmkJNdVW",
  "linkset": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/linkset",
  "contents": "/space/81246131-69a4-45ab-9bff-9c946b59cf2e/contents"
}

Benefit: explicitly point to the contents without a reserved suffix
Downside: Requires clients an additional HTTP call to get the contents. (one to get the space object and the contents property, and a second one to actually get the contents.

Alternate Option 4 - use a header or a standard query param to switch between meta and contents

I think Linked Data Platform does something like this? Not a big fan.

Alternate Option 5 - Assume a GET is always to list contents, link rel to meta

This option assumes that the most common operation is to list contents (a select * instead of a describe). so, a GET to
example.com/space/81246131-69a4-45ab-9bff-9c946b59cf2e would list the contents depending on conneg. And separately, the response would have a Link: </space/81246131-69a4-45ab-9bff-9c946b59cf2e/meta>; rel="describedby" header pointing to the space / collection description object

Dmitri's vote/recommendation

I'm leaning towards Option 0, and will explore that approach in the DCC implementation. But I'm also open to discussions if somebody objects strongly.

[dmitrizagidulin]

(Added option 0, and changed my recommendation, towards what's in PR #25)