Skip to content

API

Introduction

An API is provided, which can be accessed at ${localdb_url}/api. This API returns the result of specific queries to localDB in JSON format, which can be used to feed a Grafana dashboard. The dashboards in the dashboards directory of this repository provide example usage of the API.

Endpoint documentation

/tags/<string:tag>/serial_numbers

Endpoint to retrieve the module serialNumbers of the latest entry associated to one or more tags.

Parameters

  • tag (string): a comma-separated list of tags (e.g. "TAG1,TAG2")

Additional parameter in the query

  • verbose (boolean): if provided, return details for each serial number
  • epoch_from (float): if provided, only list serial numbers registered after this date (milliseconds since 1970)
  • epoch_to (float): if provided, only list serial numbers registered before this date (milliseconds since 1970)
  • compact: compact output with fewer fields (in conjunction with verbose)

Example query

$localdb_url/api/tags/4CBA-1,XYZ-2/serial_numbers?verbose=true

Returns

Dictionary with each tag as key and its list of serial numbers/details as value.

/sites/<string:site>/serial_numbers

Endpoint to retrieve all modules at the specified site and return a list including for each, serial numbers, chip type and current stage

Parameters:

  • site (string): a comma-separate list of sites

Additional parameter in the query:

  • verbose (boolean): if provided, return details for each serial number

Example query:

$localdb_url/api/sites/IRFU,LPNHE/serial_numbers?verbose=true

/sites/

Endpoint to retrieve the list of all sites

Returns:

List of site codes (institutions)

/sites/<string:site>/tags

Endpoint to retrieve the list of all tags for a given site.

Parameters:

  • site (string): a comma-separated list of site codes

Returns:

List of tag names associated with modules at the specified site(s)

/components

Endpoint to retrieve component serial numbers with optional filtering by component type.

Query parameters

  • type (string): filter by component type(s), comma-separated (e.g. "module,front-end_chip")

Available component types

  • bare_module
  • front-end_chip
  • module
  • module_pcb
  • ob_bare_module_cell
  • ob_cooling_block
  • ob_loaded_module_cell
  • sensor_tile

Example queries

  • $localdb_url/api/components - All components
  • $localdb_url/api/components?type=module - Only modules
  • $localdb_url/api/components?type=module,front-end_chip - Modules and front-end chips

Returns

JSON array of component serial numbers

Error responses

  • 400 Bad Request: If invalid component type(s) are provided, returns error with list of valid types

/components/<string:serial_number>/properties/, /components/<string:serial_number>/properties/<string:key>

Endpoint to retrieve component properties for a specific serial number.

Parameters

  • serial_number (string): the component serial number

Query parameters (for /properties/<string:key>)

  • key (string): specific property key to retrieve

Returns

  • Without key: JSON object with all available properties including layer, chip_type, n_chips, bom, nominal_current, current_stage, alternative_identifier, and component_type
  • With key: JSON value for the specific property key

Error responses

  • 400 Bad Request: If the requested key doesn't exist, returns error with list of valid keys