Endpoints for `aiida-explorer`

[eimrek]

The current (old) AiiDA Exporer

• is used in Materials Cloud Explore section, see e.g. https://www.materialscloud.org/explore/mc3d;
• has the source code at https://github.com/materialscloud-org/aiida-explorer;
• uses the old REST API built into aiida-core.

We're (mainly @SharanRP) working on the new AiiDA explorer (https://github.com/aiidateam/aiida-explorer) with the goal to replace the old one and the plan is to use this REST API (aiida-restapi) for it.

Currently it's not clear (maybe just undocumented, or potentially unimplmeneted) if all the endpoints that are needed are present.

Below I will list the endpoints of the old aiida REST API that the current/old AiiDA explorer is using. The goal of this issue would be to document (in documentation or examples folder) or implement all the endpoints needed for the new aiida-explorer. The new endspoints do not need to match exactly, of course, but just the data needs to be accessible.

List of old endpoints (demonstrated with the MC3D database) organized by the parts of the frontend:

• Node selection grid:
  • https://aiida.materialscloud.org/mc3d/api/v4/nodes/full_types
  • https://aiida.materialscloud.org/mc3d/api/v4/nodes/page/1?perpage=25&full_type="data.%|"&orderby=-ctime
• Node details:
  • Attributes:
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/1ca1fdc5-2bd5-44d6-ac93-66d61d593535?attributes=true
  • incoming/outgoing links/nodes:
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/1ca1fdc5-2bd5-44d6-ac93-66d61d593535/links/incoming
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/1ca1fdc5-2bd5-44d6-ac93-66d61d593535/links/outgoing
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/1ca1fdc5-2bd5-44d6-ac93-66d61d593535/links/tree?in_limit=10&out_limit=10
  • downloading a node:
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/download_formats
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/0267a642-b768-4638-aa25-a2976cc8e74e/download?download_format=upf
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/8b4cac08-928f-443a-8a26-5042d9970d76/download?download_format=cif
  • download files from file repository:
    • https://aiida.materialscloud.org/mc3d/api/v4/nodes/1ca1fdc5-2bd5-44d6-ac93-66d61d593535/repo/contents?filename="aiida.in"
  • Calcjob specific
    • https://aiida.materialscloud.org/mc3d/api/v4/calcjobs/1ca1fdc5-2bd5-44d6-ac93-66d61d593535/input_files
    • https://aiida.materialscloud.org/mc3d/api/v4/calcjobs/1ca1fdc5-2bd5-44d6-ac93-66d61d593535/output_files
• Statistics:
  • https://aiida.materialscloud.org/mc3d/api/v4/users
  • https://aiida.materialscloud.org/mc3d/api/v4/server
  • https://aiida.materialscloud.org/mc3d/api/v4/nodes/full_types_count
  • https://aiida.materialscloud.org/mc3d/api/v4/nodes/statistics

Note: could be that i missed something and will add it later.

[eimrek]

Many of the endpoints seem to be present by checking /redoc (e.g. /nodes) but everything is undocumented. Would be great to have documentation on the REST endpoints here: https://aiida-restapi.readthedocs.io/en/latest/user_guide/index.html

[eimrek]

Note that there is also a "REST migration guide" in the docs: https://aiida-restapi.readthedocs.io/en/latest/user_guide/graphql.html#rest-migration-guide

This shows how many of the required REST endpoints can be recreated via GraphQL queries.

[agoscinski]

Hey small update,

I went through the list in this issue and made a PR agoscinski#3 with examples that recreate the endpoints from the old restapi using the graphql endpoint with queries in the body of the message. I ticked the ones that we can recreate with the current state of the cade.

There is another issue #12 with a list of missing endpoints which however seems a bit out of date as it contains endpoints that are already implemented (e.g. /api/v4/nodes/<id>/). I am not sure if the idea was to support these endpoints both over fastapi and over graphql or to just drop any other fastapi endpoint than graphqll. From this issue #16 it seems that implementing dynamic queries into the fastapi needs some closer design consideration. Therefore I would for now implement missing endpoints on the side that is easier to implement.

[edan-bainglass]

@eimrek let's discuss this issue. Regarding documentation, the autodocs generated by FastAPI in ReDoc from endpoint metadata is quite rich. The downside is that one needs to launch the restapi to see them. Is there a use case where one needs documentation but has no access to the restapi? If so, we'll need to improve the static docs. Otherwise, ReDoc is where it's at!