Server

Server#

The server module has two main components: the BaseDracoRouter abstract base class to provide a template for declaring groups of API endpoints which might use a Draco instance under the hood and the DracoAPI class to handle registering the actual endpoints to a FastAPI instance and to allow for customization of the API.

You can learn more on applications of the server module in the applications section which includes examples.

BaseDracoRouter#

class draco.server.BaseDracoRouter(draco, **kwargs)#

Abstract APIRouter declaring a group of endpoints which might make use of an underlying Draco instance, injectable via the constructor.

Read more about APIRouter

__init__(draco, **kwargs)#
Parameters:

  • draco (Draco) – the underlying Draco instance to be used by the router endpoints.

  • kwargs – keyword arguments to be passed to the APIRouter constructor.

register()#

Convenience method to register the endpoints of the router by calling the _register method.

Note

As of now, this abstract class has four concrete implementations:

ClingoRouter#

Note

Defines endpoints under /clingo.

class draco.server.routers.ClingoRouter(draco, **kwargs)#

Bases: BaseDracoRouter

Router exposing Clingo functionality through REST endpoints.

__init__(draco, **kwargs)#
Parameters:

  • draco – the underlying Draco instance to be used by the router endpoints.

  • kwargs – keyword arguments to be passed to the APIRouter constructor.

DracoRouter#

Note

Defines endpoints under /draco.

class draco.server.routers.DracoRouter(draco, **kwargs)#

Bases: BaseDracoRouter

Router exposing core functionality of Draco through REST endpoints.

__init__(draco, **kwargs)#
Parameters:

  • draco – the underlying Draco instance to be used by the router endpoints.

  • kwargs – keyword arguments to be passed to the APIRouter constructor.

RendererRouter#

Note

Defines endpoints under /renderer.

class draco.server.routers.RendererRouter(draco, **kwargs)#

Bases: BaseDracoRouter

Router exposing renderer functionality through REST endpoints. To spare the round trip between the client and the server, the actual dataset to be rendered does not need to be sent to the server. The returned specification will contain an empty dataset and the client is responsible for filling it in.

__init__(draco, **kwargs)#
Parameters:

  • draco – the underlying Draco instance to be used by the router endpoints.

  • kwargs – keyword arguments to be passed to the APIRouter constructor.

UtilityRouter#

Note

Defines endpoints under /utility.

class draco.server.routers.UtilityRouter(draco, **kwargs)#

Bases: BaseDracoRouter

Router exposing utility functionality through REST endpoints.

__init__(draco, **kwargs)#
Parameters:

  • draco – the underlying Draco instance to be used by the router endpoints.

  • kwargs – keyword arguments to be passed to the APIRouter constructor.

DracoAPI#

class draco.server.DracoAPI(draco=Draco(), app=FastAPI(), base_routers=None)#

A class responsible for conveniently creating a FastAPI server exposing the capabilities of Draco. Provides sensible defaults while allowing for customization of the underlying FastAPI instance as well as the routers used to expose the Draco features in a granular way.

__init__(draco=Draco(), app=FastAPI(), base_routers=None)#

Creates a new DracoAPI instance. If no parameters are passed in, the default configuration of Draco and FastAPI is used.

The base_routers parameter governs the routers which get registered to the FastAPI instance, that is, they define the actual endpoints which will be available. Default routers get registered automatically:

  • DracoRouter - exposes the core functionality of Draco

  • ClingoRouter - exposes the functionality of the Clingo solver

  • RendererRouter - exposes renderer functionality

  • UtilityRouter - exposes various utility endpoints

If you wish to enable only a subset of these endpoints, you can pass in a list of routers to the base_routers parameter. The routers will be registered in the order they appear in the list. Note that to avoid inconsistencies between the Draco instance and the routers, you should declare a Draco instance first, use it to construct your routers, then pass it into the constructor too.

Let’s suppose that you want to enable only DracoRouter and UtilityRouter and configure them to use custom prefix and tags:



>>> from draco import Draco
>>> from draco.server.routers import DracoRouter, UtilityRouter
>>> from draco.server import DracoAPI
>>> draco = Draco()
>>> draco_router = DracoRouter(draco,
>>>                            prefix='/my-draco',
>>>                            tags=['My Draco Tag'])
>>> utility_router = UtilityRouter(draco,
>>>                                prefix='/my-utility',
>>>                                tags=['My Utility Tag'])
>>> my_base_routers = [draco_router, utility_router]
>>> my_api = DracoAPI(draco=draco, base_routers=my_base_routers)

You can use the very same method to add support for more endpoints by registering further routers.

Parameters:

  • draco (Draco) – The Draco instance to use. Use this instance to configure the Draco programs such as constraints and weights.

  • app (FastAPI) – The FastAPI instance to use. Use this instance to configure the FastAPI server according to your needs.

  • base_routers (list[BaseDracoRouter] | None) – Routers to be used by the server, defining the actual endpoints.