Skip to content

API revamp

Jump to bottom
T. Andrew Manning edited this page Jun 17, 2026 · 6 revisions

API revamp

Issues are associated with api-revamp milestone.

Problem

The Blast API is due for a major revision. The current API has evolved organically to accommodate improvements and revisions without a clearly defined overall API schema.

Goals

Goals include:

  • deduplication of redundant functionality
  • minimization of endpoints by consolidating logically connected functions and objects
  • better utilization of Django REST Framework (DRF) to implement most of the logic
  • creation of a proper OpenAPI spec for the entire Blast API, both to unambiguously define it for development purposes and to leverage the extensive OpenAPI ecosystem of tools and renderers like SwaggerUI

Original API

See table in API_endpoint_table.csv.

New API

Data objects

GET /api/cutout

Return Cutout object.

Query params:

transient (string): transient name filter (string): filter associated with desired image

Example: /api/cutout/?transient=2026dgt&filter=SDSS_r

The DRF ModelSerializer class method to_representation() can be used to override the file field values in order to generate individual download URLs. These URLs would simply insert "download/"; for example, /api/cutout/download?transient=2026dgt&filter=SDSS_r

GET /api/cutout/download

Return FITS image file.

Query params:

transient (string): transient name filter (string): filter associated with desired image

Example: /api/cutout/download?transient=2026dgt&filter=SDSS_r

Using the DRF @action decorator, a download() method can be added to the CutoutViewSet subclass to implement the view function, where DRF automatically adds the /api/cutout/download route.

class CutoutViewSet(viewsets.ReadOnlyModelViewSet):
    # ...
    @action(methods=['get'], detail=True,
            url_path='download', url_name='cutout-download')
    def download(self, request, pk=None):
        cutout = self.get_object()
        stream_download_file(cutout.fits)

Datasets

GET /api/dataset/[transient_name]

Output tabular data only. Default to JSON format but support YAML.

Query params:

format (string): "json" (default) or "yaml" revision (integer): which dataset revision to return

GET /api/dataset/[transient_name]/all

Output entire dataset as compressed archive file.

Query params:

format (string): ".tar.gz" (default) or ".zip"

GET /api/dataset/[transient_name]/file

Query params:

name (string): file name as defined by model field type (string): "cutout", "sedfittingresult_local", "sedfittingresult_global" revision (integer): which dataset revision to return

Clone this wiki locally