API endpoints

Each API endpoint has the form /api/*, and returns a JSON response. For POST requests, send data as JSON and set the Content-Type HTTP header to application/json.

Any field representing a date and time is given as a UNIX timestamp as returned by datetime.timestamp() in the Python standard library.

The output formats described below are for success cases. If an error occurs, the JSON response is of the form {"detail": "<error message>"} unless stated otherwise.

The API endpoints are:

Async process API

URL: /api/async/status/<target PK>/

Method: GET

Output: Key-value object with the following keys:

  • processes: list of processes, sorted by creation time (most recent first). Each process has the following keys:

    • identifier
    • created: creation time
    • status: string field indicating the status of the process: the possible values depend on the type of process
    • terminal_timestamp: time at which the process finished or failed, or null
    • failure_message: message explaining why the process failed, or null
    • view_url: relative URL to info page if this is a pipeline processes, or null for other process types
    • process_type: string field identifying the type of process, e.g. TimelapsePipeline

  • timestamp: current server time. This is useful for web clients that poll the API to detect when a process finishes, since the first received timestamp can be compared with the process’s terminal_timestamp to exclude processes that were already finished at the time of page load.

Example output:

{
  "timestamp": 1569512837.025409,
  "processes": [
    {
      "identifier": "astrosource_1_20190926154552",
      "created": 1569512752.759492,
      "status": "failed",
      "terminal_timestamp": 1569512753.583918,
      "failure_message": "All Stars Removed. Try removing problematic files or raising the imageFracReject",
      "view_url": "/pipeline/17",
      "process_type": "AstrosourceProcess"
    },
    {
      "identifier": "timelapse_1_20190926154515",
      "created": 1569512715.513135,
      "status": "created",
      "terminal_timestamp": 1569512717.150723,
      "failure_message": null,
      "view_url": "/pipeline/16",
      "process_type": "TimelapsePipeline"
    }
  ]
}

Pipeline process API

URL: /api/pipeline/logs/<pipeline PK>/

Method: GET

Output: A single key-value object which contains all the fields in the processes objects from the async process API and the following additional fields:

  • logs: log output from the pipeline process (see the pipeline documentation on logging)
  • group_name: the name of the DataProductGroup which stores the outputs of this pipeline process, or null if the group has not yet been created.
  • group_url: relative URL to the info page for the associated DataProductGroup, or null if the group has not yet been created.

Example output:

{
  "identifier": "dummy_m13_2019-07-22-163925",
  "created": 1563813565.83185,
  "status": "created",
  "terminal_timestamp": 1563813673.560319,
  "failure_message": null,
  "view_url": "/pipeline/45",
  "logs": "Processing test_dp_ftfn0m410-kb23-20190413-0059-e91.fits.fz",
  "group_name": "dummy_m13_2019-07-22-163925_outputs",
  "group_url": "/dataproducts/data/group/37/"
}

Target detail and timelapses API

URL: /api/target/<target PK>/

Method: GET

Output: Key-value object with the following keys:

  • target: key-value object:

  • timelapses: list of timelapses sorted by creation time (most recent first). Each timelapse object has the following keys:

    • name: basename of timelapse filename
    • format: the format of the timelapse (e.g. gif)
    • url: relative URL from which the timelapse can be downloaded
    • created: creation time
    • frames: the number of frames that comprise the timelapse

Example output:

{
  "target": {
    "name": "Hercules Globular Cluster",
    "extra_fields": {
      "mykey": "myvalue"
    }
  },
  "timelapses": [
    {
      "name": "timelapse_1_20190926154515_t.gif",
      "format": "gif",
      "url": "/data/Hercules%20Globular%20Cluster/none/timelapse_1_20190926154515_t.gif",
      "created": 1569512717.150723,
      "frames": 2
    }
  ]
}

Create observation alert API

URL: /api/observe/

Method: POST

Input: A key-value JSON object with the following keys:

  • target: primary key for the target object
  • template_name: the name of the observation template to use
  • facility: observing facility: currently only LCO is supported
  • overrides: key-value mapping for form fields to override after populating fields through the observation template
  • email: email address to associate with the observation alert

Output: The input JSON data is returned as output on success. If the input is invalid, the response is of the form {"<field_name>": ["<error message", ...], ...} with error message(s) for each invalid field, or {"detail": "<error message>"} for non-field errors.

Example input:

{
  "target": 1,
  "template_name": "my-template",
  "facility": "LCO",
  "overrides": {
    "start": "2019-08-05T00:00:00",
    "end": "2019-08-10T00:00:00"
  },
  "email": "someone@someplace.net"
}

Rate throttling

This endpoint uses Django REST Framework’s throttling to prevent abuse by limiting the number of observation alerts that can be created per minute. This is controlled by the REST_FRAMEWORK setting, which is set as follows by the setup script:

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.ScopedRateThrottle',
    ],
    'DEFAULT_THROTTLE_RATES': {
        'observe': '6/minute',
    },
}

The observe key can be changed to alter the throttling rate.