DRS bundle contents pagination

[jb-adams]

Issues: #366 , #325

Built Docs: link

This PR aims to specify pagination of the contents array for a single DRS Object. This is done by adding a page request query parameter, and a Link response header to inform the client of the traversal links to various pages.

Open Questions:

• A DRS Object has multiple array-type attributes. In addition to contents there is also checksums, access_methods, aliases. Do we foresee any of these attributes requiring pagination as well? If yes, we would likely need to rename the new parameter and header to avoid collision downstream (e.g. Link to ContentsLink)
• Does this introduction constitute a breaking change, since pagination is introduced on an existing endpoint that didn't have it previously? If so, we should think about how to get around this (such as another new query parameter that, when absent, causes the server to return the default, non-paginated response)

[jb-adams]

Additional notes/questions:

• for the POST /objects/{object_id} endpoint, page is still currently listed as a query string param. This is to keep it aligned with the links returned in the Link header
• if we decide to rename Link to ContentsLink (or something similar) to make it explicit that it's for contents pagination, we should also rename the query string parameter from page to contents_page (for example).

[ianfore]

See also #377

[jb-adams]

Following the Jan 10th Cloud WS call, I moved the paginated contents array function to 2 new endpoints:

• GET /objects/{object_id}/contents
• POST /objects/{object_id}/contents

This was done to address the original awkwardness of having pagination for an attribute within the returned DrsObject. Now, the pagination affects the top-level array of the response. @patmagee @aniewielska

We may need to back up the conversation a bit though, as @dglazer and @ianfore propose in #377 dropping bundles, and hence contents pagination, altogether. I'd prefer to arrive at an answer on whether bundles should be scrapped before doing more work in the branch.

@MichaelLukowski it would be really helpful to get your feedback on the U Chicago bundle use case to inform the conversation.

@briandoconnor

[MichaelLukowski]

@jb-adams in our experience of implementing bundles we have found that they grow to be too large and pagination becomes difficult to implement. We are in favor of dropping bundles and moving forward with the batch approach. As discussed in the FASP hackathon U Chicago is working on a "packaging" approach that doesn't have to be standardized but could be used as a "best-practice"

[jb-adams]

Thanks for the feedback @MichaelLukowski ! Can you also relay your preference to drop bundles in thread #377 ? That's the PR that would remove bundles from the spec