search

Materials-Consortia / OPTIMADE

Specification of a common REST API for access to materials databases
https://optimade.org/specification
Creative Commons Attribution 4.0 International
83 stars 37 forks source link

Is the dictionary of available_api_versions in the wrong order? #65

Closed rartino closed 5 years ago

rartino commented 5 years ago

I'm running in some trouble with the available_api_versions property in the info endpoint. The example specify it like this:

        "available_api_versions": {
          "0.9.5": "http://db.example.com/optimade/v0.9/",
          "0.9.2": "http://db.example.com/optimade/v0.9.2/",
          "1.0.2": "http://db.example.com/optimade/v1.0/"
        },

This makes it impossible to serve the same API version on two different URLs. But, that seems a very natural thing to want to do. E.g., if one's implementation supports up to v0.9.5, then to let both http://db.example.com/optimade/v0.9/ and http://db.example.com/optimade/v0.9.5/ both serve 0.9.5 seems the right thing to do.

So, would it not make more sense if we defined the dictionary the other way around?, i.e.,

        "available_api_versions": {
          "http://db.example.com/optimade/v0.9/": "0.9.5",
          "http://db.example.com/optimade/v0.9.5/": "0.9.5",
          "http://db.example.com/optimade/v0.9.2/": "0.9.2",
          "http://db.example.com/optimade/v1.0/": "1.0.2"
        },

Or, if we want the dictionary in this order, perhaps we can let the URL be a list?,

        "available_api_versions": {
          "0.9.5": ["http://db.example.com/optimade/v0.9/, http://db.example.com/optimade/v0.9.5/"],
          "0.9.2": ["http://db.example.com/optimade/v0.9.2/"],
          "1.0.2": ["http://db.example.com/optimade/v1.0/]"
        },
merkys commented 5 years ago

We could in principle extend the current specification to provide lists for versions that have more than one URL:

        "available_api_versions": {
          "0.9.5": ["http://db.example.com/optimade/v0.9/, http://db.example.com/optimade/v0.9.5/"],
          "0.9.2": "http://db.example.com/optimade/v0.9.2/",
          "1.0.2": "http://db.example.com/optimade/v1.0/"
        },

Allowing lists with multiple URLs would make both @rartino's 1) and 3) examples also valid (and would be backwards-compatible).

rartino commented 5 years ago

Oh, right, this one we probably want to get right for v0.10 as well.

rartino commented 5 years ago

I noticed just now that the present definition of available_api_versions uses data values as keys. I think this technically isn't violating the (latest) letter of the standard, but its spirit.

Since we are making a bunch of backwards incompatible changes now anyway, is anyone opposed to going for: 

        "available_api_versions": [
           {
              version="0.9.5",
              url="http://db.example.com/optimade/v0.9/"
           }, 
           {
              version="0.9.5",
              url="http://db.example.com/optimade/v0.9.5/"
           }, 
           {
              version="0.9.2",
              url="http://db.example.com/optimade/v0.9.2/"
           }, 
           {
              version="1.0.2",
              url="http://db.example.com/optimade/v1.0/"
           }, 
        ],

It is a tiny bit more work to parse on the client side, but correspondingly easier to compose on the server side.

merkys commented 5 years ago

I'm fine with the latest proposal.

rartino commented 5 years ago

blocking-release moved to the correspoding PR.