class xpublish.Rest(datasets=None, routers=None, cache_kws=None, app_kws=None, plugins=None)[source]

Used to publish multiple Xarray Datasets via a REST API (FastAPI application).

To publish a single dataset via its own FastAPI application, you might want to use the xarray.Dataset.rest accessor for more convenience. Additionally the xpublish.SingleDatasetRest class allows has a simplified interface for single dataset access.

  • datasets (Optional[Dict[str, Dataset]]) – A mapping of datasets objects to be served. If a mapping is given, keys are used as dataset ids and are converted to strings. See also the notes below.

  • routers (Optional[APIRouter]) – A list of dataset-specific fastapi.APIRouter instances to include in the fastAPI application. These routers are in addition to any loaded via plugins. The items of the list may also be tuples with the following format: [(router1, {'prefix': '/foo', 'tags': ['foo', 'bar']})], where the 1st tuple element is a fastapi.APIRouter instance and the 2nd element is a dictionary that is used to pass keyword arguments to fastapi.FastAPI.include_router().

  • cache_kws (Optional[Dict]) – Dictionary of keyword arguments to be passed to cachey.Cache.__init__(). By default, the cache size is set to 1MB, but this can be changed with available_bytes.

  • app_kws (Optional[Dict]) – Dictionary of keyword arguments to be passed to fastapi.FastAPI.__init__().

  • plugins (Optional[Dict[str, Plugin]]) – Optional dictionary of loaded, configured plugins. Overrides automatic loading of plugins. If no plugins are desired, set to an empty dict.


The urls of the application’s API endpoints differ whether a single dataset or a mapping (collection) of datasets is given. In the latter case, all dataset-specific endpoint urls have the prefix /datasets/{dataset_id}, where {dataset_id} corresponds to the keys of the mapping (converted to strings). Still in the latter case, the endpoint /datasets is added and returns the list of all dataset ids.

__init__(datasets=None, routers=None, cache_kws=None, app_kws=None, plugins=None)[source]


__init__([datasets, routers, cache_kws, ...])


FastAPI dependencies to pass to plugin router methods


Attempt to load dataset from plugins, otherwise return dataset from passed in dictionary of datasets


Return dataset ids from directly loaded datasets and plugins


Set up FastAPI application kwargs


Set up cache kwargs


Load the app and dataset routers for plugins

register_plugin(plugin[, plugin_name, overwrite])

Register a plugin with the xpublish system

serve([host, port, log_level])

Serve this FastAPI application via uvicorn.run().


Initialize datasets and dataset accessor function


Initialize and load plugins from entry_points unless explicitly provided



Returns the fastapi.FastAPI application instance.


Returns the cachey.Cache instance used by the FastAPI application.


Returns the loaded plugins