Skip to content

API revamp

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

API revamp

Issues are associated with api-revamp milestone.

The pull requests associated with the milestone will be closed simultaneously by a consolidated feature branch called api-revamp. As PRs are considered ready for merging, the associated feature branches will be merged into api-revamp while the PRs are left open. When api-revamp is ready for merging to close the milestone, there will be a single Blast version increment and changelog entry.

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