HTTP API

Standards

Tiled’s HTTP API follows the OpenAPI v3 specification. Additionally, it follows the JSON API standard.

When Tiled is configured to use an Authenticator, it adds routes that comply with the OAuth2 protocol. Specifically, it implements “sliding sessions” with access and refresh tokens that are JWTs. See Security for an overview and Authentication Details for details.

Overview

The routes are generally spelled like GET /{action}/{path}/, like GitHub repository URLs, with the path following the structure of the Tree entries.

The GET /node/metadata/{path} route provides the metadata about one node. The GET /node/search/{path} route provides paginated access to the children of a given node, with optional filtering (search). The GET /node/full/{path} route provides all the metadata and data below a given node.

Specialized data access routes GET /array/block/{path}, GET /array/full/{path}, and GET /dataframe/partition/{path} provide options for slicing and sub-selection specific to arrays and dataframes. Generic clients, like a web browser, should use the “full” routes, which send the entire (sliced) result in one response. More sophisticated clients with some knowledge of Tiled may use the other routes, which enable parallel chunk-based access.

The POST /token route accepts form-encoded credentials and responds with an access token and a refresh token. The POST /token/refresh route accepts a refresh token and responds with a new set of tokens.

The root route, GET / provides general information about the server and the formats it supports.

Reference

To view and try the interactive docs, start the Tiled server with the demo Tree from a Terminal

tiled serve pyobject --public tiled.examples.generated:tree

and navigate your browser to http://localhost:8000/docs.

A non-interactive reference with the same content follow below.

GET /

About

Status Codes
  • 200 OK – Successful Response

GET /array/block/{path}

Array Block

Fetch a chunk of array-like data.

Parameters
  • path (string) –

Query Parameters
  • format (string) –

  • block (string) – (Required)

  • slice (string) –

  • expected_shape (string) –

Status Codes
GET /array/full/{path}

Full Array

Fetch a slice of array-like data.

Parameters
  • path (string) –

Query Parameters
  • format (string) –

  • slice (string) –

  • expected_shape (string) –

Status Codes
GET /dataframe/partition/{path}

Dataframe Partition

Fetch a partition (continuous block of rows) from a DataFrame.

Parameters
  • path (string) –

Query Parameters
  • partition (integer) – (Required)

  • field (array) –

  • format (string) –

Status Codes
GET /node/full/{path}

Full Xarray.Dataset

Fetch the data below the given node.

Parameters
  • path (string) –

Query Parameters
  • field (array) –

  • format (string) –

Status Codes
GET /node/metadata/{path}

Node Metadata

Fetch the metadata and structure information for one entry.

Parameters
  • path (string) –

Query Parameters
  • fields (array) –

  • select_metadata (string) –

  • omit_links (boolean) –

  • root_path (string) –

Status Codes