OPTIMADE Gateway

A REST API server acting as a gateway for databases with an OPTIMADE API, handling the distribution and collection of a single query to several different OPTIMADE databases.

The design outline is available here.

Known limitations

Here follows a list of known limitations and oddities of the current OPTIMADE gateway code.

Pagination

Pagination is a bit awkward in its current implementation state.

When using the page_limit query parameter for a gateway query for gateways with multiple databases, i.e., for GET /gateways/{gateway ID}/structures and GET /queries/{query ID}, the resulting entry-resource number is the product of the page_limit value and the number of databases in the gateway (maximum). This is because the page_limit query parameter is passed straight through to the external database requests, and the returned entries are stitched together for the gateway response.

So effectively, when querying GET /gateways/{gateway with N databases}/structures?page_limit=5 the resulting (maximum) number of entries returned in the response (the size of the data array in the response) will be N x 5, and not 5 as would otherwise be expected.

The intention is to fix this in the future, either through short-time caching of external database responses, or figuring out if there is a usable algorithm that doesn't extend the number of external requests (and therefore the gateway response times) by too much.

Sorting

Sorting is supported for all the gateway's own resources, i.e., in the /gateways, /databases, and /queries endpoints. But sorting is not supported for the results from external OPTIMADE databases. This means the sort query parameter has no effect in the GET /gateways/{gateway ID}/structures and GET /queries/{query ID} endpoints.

This shortcoming is a direct result of the current page_limit query parameter handling, and the limitation of the same.

License, copyright & funding support

All code in this repository was originally written by Casper Welzel Andersen (@CasperWA). The design for the gateway as outlined in design.md was a joint effort between Casper Welzel Andersen & Carl Simon Adorf (@csadorf).

All files in this repository are licensed under the MIT license with copyright © 2021 Casper Welzel Andersen & THEOS, EPFL.

Funding support

This work was funded by THEOS, EPFL and the MarketPlace project.

The MarketPlace project is funded by Horizon 2020 under H2020-NMBP-25-2017 call with Grant agreement number: 760173.