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 guess my main driving motivation is that I think it’s very common that the same resource is described via different standards and those standards can also be converted into each other (ideally by the xRegistry server itself). Therefore, one resource can have multiple versions (a collection), which each can be described via different document formats (a collection, too).

Allthough with REST you could argue that a different document formats is a different content type. But with this I’m afraid that we’ll confuse content types between the format of the registry and its metamodel itself (application/json), the content type of the serialization format of the metadata formats (usually application/json) and then the fact what kind of format it really is (e.g., OpenAPI v3 or AsyncAPI 2.1).

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!