xRegistry HTTP operations structure

xregistry-http-structure-thoughts.md

Idea for xRegistry spec:

• One resource can not only have multiple versions, but also multiple documents representations of it
• Ideally, there is just one document that is the source of truth, but other documents can be automatically derived from it
  • E.g. an API could be described with EDMX, and the OpenAPI 2, OpenAPI3 and 3.1 definitions of it are derived
  • Consumers may only support certain document description formats and would like to see which ones are available and pick the best choice to them
    • A consumer may not care which document formats are derived or original.
• Like versions, the document formats should have a "default" fallback.
• For server and consumer it would be easier if API operations are not polymorphic and return different responses based on a query parameter

/                                              # Access the Registry
/model                                         # Access the Registry model definition
/GROUPs                                        # Access a Group Type
/GROUPs/gID                                    # Access a Group
/GROUPs/gID/RESOURCEs                          # Access a Resource Type
/GROUPs/gID/RESOURCEs/rID/document             # Access the latest Resource Versions default document
/GROUPs/gID/RESOURCEs/rID/meta                 # Metadata about the latest Resource Version, with possible "inline"

/GROUPs/gID/RESOURCEs/rID/versions                            # Show versions of a Resource
/GROUPs/gID/RESOURCEs/rID/versions/vID/meta                   # Metadata about a Version, with possible "inline"
/GROUPs/gID/RESOURCEs/rID/versions/vID/document               # Access a Versions default document representation
/GROUPs/gID/RESOURCEs/rID/versions/vID/document/formats       # Show all representation formats, available for the version
/GROUPs/gID/RESOURCEs/rID/versions/vID/document/formats/fID   # Access a particular document representation format (formatID)

I think one the issues we'll run into is that a URL like /GROUPs/gID/RESOURCEs/rID/meta, in our model, is also meant to be a JSON-Path type of expression. And the .../rID/meta would normally step into a meta property. Which is why Clemens was so adamant about us using maps instead of arrays. And since .../rID, technically, would be in a format that we don't have control over it might be odd to have .../meta not do anything with that doc. Let's discuss on one of our calls.

Ok, I haven't thought about the JSON Path aspect of it!