Proposal for an objects endpoint

[philipnbbc]

This PR proposes an objects endpoint that includes a list of Flows that references the target media object.

The proposal also adds a property that holds the ID of the Flow that first referenced (via a Flow Segment) the media object. The proposal contains some questions around making the property required rather than optional (as currently specified) and whether a user should be able to set it.

Jira Issue (if relevant)

Jira URL: https://jira.dev.bbc.co.uk/browse/CLOUDFIT-3550

Related PRs

Where appropriate. Indicate order to be merged.

Submitter PR Checks

(tick as appropriate)

• PR completes task/fixes bug
• API version has been incremented if necessary
• ADR status has been updated, and ADR implementation has been recorded
• Documentation updated (README, etc.)
• PR added to Jira Issue (if relevant)
• Follow-up stories added to Jira

Reviewer PR Checks

(tick as appropriate)

• PR completes task/fixes bug
• Design makes sense, and fits with our current code base
• Code is easy to follow
• PR size is sensible
• Commit history is sensible and tidy

Info on PRs

The checks above are guidelines. They don't all have to be ticked, but they should all have been considered.

[j616]

A couple of questions in line. I'm also wondering if it's worth considering allowing querying by a list of object IDs. Mainly because one of our key use cases is removing all instances of content. This will likely take the form of obtaining a list of object IDs from a flow, querying this endpoint for all those IDs, then calling DELETE against all of those flows with the object IDs. The requests will add up quickly. That said, I don't currently think we expect this feature to be needed often!

[philipnbbc]

A couple of questions in line. I'm also wondering if it's worth considering allowing querying by a list of object IDs. Mainly because one of our key use cases is removing all instances of content. This will likely take the form of obtaining a list of object IDs from a flow, querying this endpoint for all those IDs, then calling DELETE against all of those flows with the object IDs. The requests will add up quickly. That said, I don't currently think we expect this feature to be needed often!

Maybe the endpoint should be renamed to /objects-query? That is better to allow a GET /objects-query?object_id= for a simple single object lookup and POST /objects-query for multiple objects. Adding POST /objects would be a little confusing / unexpected.

[j616]

Maybe the endpoint should be renamed to /objects-query? That is better to allow a GET /objects-query?object_id= for a simple single object lookup and POST /objects-query for multiple objects. Adding POST /objects would be a little confusing / unexpected.

I was thinking a list in the query string. But thinking about it now, I seem to remember that when we recently looked into that for other purposes, we found the options unsatisfactory.

[philipnbbc]

Maybe the endpoint should be renamed to /objects-query? That is better to allow a GET /objects-query?object_id= for a simple single object lookup and POST /objects-query for multiple objects. Adding POST /objects would be a little confusing / unexpected.
I was thinking a list in the query string.

I didn't think adding potentially hundreds of object IDs into the query string was ideal and that's why a POST seemed better. A POST is also used to make queries to DynamoDB for example.

[j616]

I didn't think adding potentially hundreds of object IDs into the query string was ideal and that's why a POST seemed better. A POST is also used to make queries to DynamoDB for example.

Fair point. Let's leave it for now and see what use cases actually pop up in the real world. I think if we do anything in this space, we should explore how we can provide some level of consistency with the rest of the API.

[philipnbbc]

I've changed my mind following James' comments on the query parameter. The object ID is now a path component of the URL. This matches what the S3 API does for example and also makes it more consistent with the other endpoints.