add providers to openapi.json

[ltalirz]

fixes #193

The OpenAPI 3 specification allows the addition of a list of servers to
the openapi.json file:
https://swagger.io/docs/specification/api-host-and-base-path/

This is can be used to get a fully interactive swagger documentation,
which also allows users to make requests.

Try it live
(and, in particular, use it to try out queries)

The idea is to replace the "API Documentation" link on http://www.optimade.org/ by this

So far, this PR contains just the basics to make it work. Happy to improve configurability / think about default behavior etc.

[codecov]

Codecov Report

Merging #303 (36a9c18) into master (3c8c47f) will decrease coverage by 0.15%.
The diff coverage is 16.66%.

❗ Current head 36a9c18 differs from pull request most recent head a231f9f. Consider uploading reports for the commit a231f9f to get more accurate results

@@            Coverage Diff             @@
##           master     #303      +/-   ##
==========================================
- Coverage   90.03%   89.88%   -0.16%     
==========================================
  Files          54       54              
  Lines        2268     2273       +5     
==========================================
+ Hits         2042     2043       +1     
- Misses        226      230       +4     

Flag	Coverage Δ
unittests	89.88% <16.66%> (-0.16%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
optimade/server/main.py	73.01% <0.00%> (-4.96%)	⬇️
optimade/server/config.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3c8c47f...a231f9f. Read the comment docs.

[CasperWA]

Will this fix and close #193?

[CasperWA]

You should add https://optimade.odbx.science as well I think, this is @ml-evs's implementation based on this repo.
Maybe @shyamd can lead you to a CORS ready implementation as well? And maybe also @markus1978?

[ml-evs]

It sounds like "test databases" are going to be useful for the final NaCl paper query, would it make sense to link to that one here? I'm guessing I'll host it at https://optimade-test.odbx.science if you want to put that link up.

[ltalirz]

It sounds like "test databases" are going to be useful for the final NaCl paper query, would it make sense to link to that one here?

Definitely.
Happy to add whatever DB links you can suggest.

Please also have a look at the PR when you find time; if possible, I'd like to make all changes in one go.

Cheers!

[ml-evs]

Hi @ltalirz, this was a nice idea that we've forgotten about!

I just have two concerns now:

1. This package now provides the "ground truth" schemas for the specification repo, which probably shouldn't include the server list, so we'll need to differentiate in the invoke tasks what the purpose of the generated specification is (e.g. invoke generate_openapi_with_servers or something)
2. How do we decide which implementations to include in this list, now that we potentially have so many? I have some code in Moving and adding some utilities for client code #589 that grabs all sub-db's from implementations in the provider list, but it would be nice if this was more dynamic.

[ltalirz]

Maybe host it somewhere else and include it via $ref ?

[ltalirz]

1. This package now provides the "ground truth" schemas for the specification repo

Just to understand: these schemas are copied over / replicated to the specification repo?
Would a servers field in the openapi spec pose a problem for this procedure (would it not just be ignored)?

It's certainly possible to create another copy of the openapi spec for the swagger UI - it's just that then there are two openapi specs in the repo instead of just one.

In terms of fetching the list of servers - is there now a list hosted elsewhere that one could use to fetch those programmatically?

[JPBergsma]

Are you sure this url: "https://dev-aiida-dev.materialscloud.org/optimade-sample/optimade" is correct?
I could not connect to it.
See also cors_providers.json

[ltalirz]

oh, I just saw this

I certainly cannot remember ever doing that (sorry if I did this "in my dreams" ;-) )... I still think the idea in this PR makes sense but I currently don't have time to work on it.

The updated URL would be https://aiida.materialscloud.org/optimade-sample/optimade

[JPBergsma]

Thank you for providing the correct link.
In May, I started a Postdoc at Cecam and I will be working on the Optimade project. Therefore, Matthew made me code owner for part of the code. Perhaps this triggered the review request. As I am still quite new to the project, I think it would be better to let Matthew and Casper decide about what to do with this pull request.

[ml-evs]

I think this PR is now pretty stale, please feel free to reopen if someone still wants this in.