Reserved `tags` collection

[thegagne]

Floating an idea out here: reserving the tags field for an array of strings on any resource, which can be made available with a tags collection and tagged-resources collection. Though if tags might be risky for collision with what other people might use it for, so we could make it resource-tags and tagged-resources .

These would be probably be read-only collections like the operations collection, and it would be understood that all APIs would update the tags datastore as they operate on their resources.

This is somewhat hypothetical, but inspired by $DAYJOB which is currently implementing a tagging API for our classic product APIs (which doesn't follow AEP).

There's probably some consideration for safe strings for tag id, and whether or not to have tag-values as a separate tracked thing. Just floating the idea to see if it has merit here as part of the next AEP as an optional reserved collection.

Examples:

# Create tagged resource
POST /puzzles?id=wizard-of-oz-500
Content-Type: application/json

{
  "id": "wizard-of-oz-500",
  "title": "Wizard of Oz 500-Piece",
  "tags": ["kansas", "vintage"]
}

201 Created

{
  "path": "/puzzles/wizard-of-oz-500",
  "id": "wizard-of-oz-500",
  "title": "Wizard of Oz 500-Piece",
  "tags": ["kansas", "vintage"]
}

# Look at tags collection, not much to see here other than they exist.
GET /tags
200 OK
{
  "tags": [
    {
      "path": "/tags/kansas",
      "id": "kansas"
    },
    {
      "path": "/tags/vintage",
      "id": "vintage"
    }
  ],
  "next_page_token": ""
}

# Look at tagged-resources "kansas"

GET /tags/kansas/tagged-resources

200 OK

{
  "tagged_resources": [
    {
      "path": "/tags/kansas/tagged-resources/puzzle~wizard-of-oz-500",
      "resource": "/puzzles/puzzle~wizard-of-oz-500"
    }
  ],
  "next_page_token": ""
}