API gateway and wrappers

Overview

Calls to backend services are routed via the API gateway, which is the central service in ASKCOS for API management. The API gateway is implemented with FastAPI, and consists mainly of wrappers for routing API calls to backend services, as well as utils which define endpoints for lightweight services such as drawing and authentication within the gateway itself. Typically, to integrate a new containerized backend service into ASKCOS after it is working standalone, the corresponding new wrapper(s) need to be added into the API gateway by modifying askcos2_core.

Adding a wrapper to the API gateway

A wrapper is essentially a .py file which defines functions to query backend service(s) via http requests. We will use the wrapper for scscore as the reference. You may simply copy the file and place it under your new wrapper folder under askcos2_core as the starting point. Then make a few (mostly bookkeeping) changes as needed:

• Redefine a *Input class with the field(s) that your backend service expects
• Redefine a *Output class with the field(s) that your backend service returns
• Redefine a *Response class with the field(s) that will be returned to the API gateway
• Redefine the convert_output_to_response() function. Think of it as any error handling and/or post-processing you want.
• Replace all other occurrences of scscore or SCScore with your new service name.

The definition of these Input/Output/Response classes, along with type-hintting, helps take full advantage of FastAPI's capability to automatically generate API documentation. Please always inherit from BaseWrapper in which a few abstractions have been defined, unless you know what you're doing. In particular, we reworked the asynchronous workflows which are necessary for API calls from the frontend and for long-running tasks. The logic for asynchronous task management has been abstracted away and standardized as the /call-async endpoint within each wrapper.

Updating the config file

Once the wrapper .py is implemented and registered (which happens automatically at deployment time with the @register_wrapper() function), it needs to be logged in the central module config file, e.g. module_config_full.py:

• Add your wrapper under "modules_to_start". You'll need to stick with the exact "name" you used in @register_wrapper().
• Add a config dict similar to the existing ones with the "name" as the key.

Updating ASKCOS deployment

askcos2_core $ make stop; make update

And now you should be able to see the new endpoint at the centralized API documentation.