Introduction#

If you’ve read through Why Xpublish you’ll know that Xpublish is a foundational building block for data servers. The real trick behind Xpublish is that it builds upon the Xarray datasets that the Python data community is used too.

To introduce new users to Xpublish, quickly serve a single dataset, and to allow for quick development, Xpublish includes an Xarray accessor.

Server-Side#

To begin, import Xpublish and open an Xarray Dataset:

import xarray as xr
import xpublish

ds = xr.tutorial.open_dataset(
    "air_temperature",
    chunks=dict(lat=5, lon=5),
)

To publish the dataset, use the SingleDatasetRest class:

rest = xpublish.SingleDatasetRest(ds)

Alternatively, you might want to use the xarray.Dataset.rest accessor for more convenience:

ds.rest

The same accessor is registered on xarray.DataTree — dt.rest works exactly like ds.rest. See the DataTrees tutorial for how hierarchical data is served and navigated.

Optional customization of the underlying FastAPI application or the server-side cache is possible, e.g.,

ds.rest(
    app_kws=dict(
        title="My Dataset",
        description="Dataset Description",
        openapi_url="/dataset.JSON",
    ),
    cache_kws=dict(available_bytes=1e9),
)

Serving the dataset then requires calling the serve() method on the Rest instance or the xarray.Dataset.rest accessor:

rest.serve()

# or

ds.rest.serve()

serve() passes any keyword arguments on to uvicorn.run() (see Uvicorn docs).

Default API routes#

By default, the FastAPI application created with Xpublish provides the following endpoints to get some information about the published dataset:

  • /: returns xarray’s HTML repr.

  • /keys: returns a list of variable keys, i.e., those returned by xarray.Dataset.variables.

  • /info: returns a JSON dictionary summary of a Dataset variables and attributes, similar to xarray.Dataset.info().

  • /dict: returns a JSON dictionary of the full dataset.

  • /versions: returns JSON dictionary of the versions of Python, Xarray and related libraries on the server side, similar to xarray.show_versions().

Zarr access moved to xpublish-zarr

Previous versions of Xpublish shipped a built-in Zarr plugin exposing /zarr/.zmetadata and /zarr/{var}/{key} endpoints. Starting with this release the Zarr plugin lives in its own package, xpublish-zarr. Install it separately (e.g. pip install xpublish-zarr) and register it on the Rest app to restore the previous Zarr-compatible endpoints.

Additional data access endpoints (such as Zarr-compatible access via xpublish-zarr) can be added by installing or writing plugins.

API Docs#

Thanks to FastAPI and Swagger UI, automatically generated interactive documentation is available at the /docs URL.

This path can be overridden by setting the docs_url key in the app_kws dictionary argument when initializing the rest accessor.

Client-Side#

Xpublish’s endpoints can be queried programmatically with any HTTP client. For example:

import requests

response = requests.get("http://0.0.0.0:9000/info").json()