Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

REST API docs via OpenAPI #316

Merged
merged 9 commits into from
Jan 24, 2024
5 changes: 3 additions & 2 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
# -- Project information -----------------------------------------------------

project = "imap_processing"
copyright = "2023, Regents of the University of Colorado"
copyright = "2024, Regents of the University of Colorado"
author = "IMAP Science Operations Center"

# The full version, including alpha/beta/rc tags
Expand All @@ -37,11 +37,12 @@
# ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autosectionlabel",
"sphinx.ext.autosummary",
"sphinx.ext.intersphinx", # Link to other projects' documentation
"sphinx.ext.githubpages", # Helpful for publishing to gh-pages
"sphinx.ext.napoleon",
"sphinx.ext.autosectionlabel",
bourque marked this conversation as resolved.
Show resolved Hide resolved
"sphinxcontrib.openapi",
"numpydoc",
]

Expand Down
65 changes: 65 additions & 0 deletions docs/source/data-access-api/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
.. _data-access-api:

Data Access API
===============

The SDC provides a REST API that allows users to upload and download files, as
well as query for file metadata. The following documentation describes the
various endpoints that are supported and how to use them.

The API can be accessed from the following URL: https://api.dev.imap-mission.com


.. openapi:: openapi.yml
:group:
:include: /upload/science

**Example Usage:**

.. code-block:: bash
curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/upload/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf
**Possible Responses:**

.. code-block:: json
{"statusCode": 200, "body": "https://sds-data.s3.amazon.com/imap/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf?<credentials-string>"}
{"statusCode": 400, "body": "A pre-signed URL could not be generated. Please ensure that the file name matches mission file naming conventions."}
.. openapi:: openapi.yml
:group:
:include: /download

**Example Usage:**

.. code-block:: bash
curl -X GET -H "Accept: application/json" /codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf
curl -X GET -H "Accept: application/json" imap_codice_l1a_lo_20260101_20260102_v01-01.cdf
**Possible Responses:**

.. code-block:: json
{"statusCode": 302, "headers": {"Content-Type": "text/html", "Location": "s3://sds-data/imap/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01"}, "body": {"download_url": "s3://sds-data/imap/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01"}}
{"statusCode": 400, "body": "Not a valid S3 URI. Example input: s3://bucket/path/file.ext"}
.. openapi:: openapi.yml
:group:
:include: /query

**Example Usage:**

.. code-block:: bash
curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/query?instrument=mag&data_level=l0&descriptor=burst&start_date=20230112&end_date=20230113&version=*&extension=pkts
**Possible Responses:**

.. code-block:: json
{"statusCode": 200, "headers": {"Content-Type": "application/json", "Access-Control-Allow-Origin": "*"}, "body": "[('mag', 'l0', 'burst', '20230112', '20230113', 'v01-01', 'pkts'), ('mag', 'l0', 'burst', '20230112', '20230113', 'v01-02', 'pkts')]"}
{"statusCode": 400, "headers": {"Content-Type": "application/json", "Access-Control-Allow-Origin": "*"}, "body": "<param> is not a valid query parameter. Valid query parameters are: <valid parameters>"}
157 changes: 157 additions & 0 deletions docs/source/data-access-api/openapi.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
openapi: 3.0.0
servers:
- description: Development IMAP SDC Server
host: https://api.dev.imap-mission.com/
info:
version: "0.1.0"
title: IMAP SDC API
description: Describes the API endpoints for interacting with the IMAP SDC

paths:

'/upload/science/{filepath}':
get:
tags:
- Upload
summary: Upload a science file to the SDC
parameters:
- name: filepath
in: path
required: true
description: |
The full path to the file to upload, relative to the ``IMAP_DATA_DIR`` environment variable or the user's
current working directory. (e.g. ``{IMAP_DATA_DIR}/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf``).
The filename must be a valid IMAP filename that follows the conventions described
`here <https://imap-processing.readthedocs.io/en/latest/development-guide/style-guide/naming-conventions.html#data-product-file-naming-conventions>`_.
schema:
type: string
responses:
'200':
description: Successful upload
content:
application/json:
schema:
type: array
items:
type: string
format: uri
'400':
description: Invalid or missing filename
content:
application/json:
schema:
type: array
items:
type: string

'/download/{filepath-or-filename}':
get:
tags:
- Download
summary: Download a file from the SDC
operationId: download
parameters:
- in: path
name: filepath-or-filename
description: |
The filename to download (e.g. ``imap_codice_l1a_lo_20260101_20260102_v01-01.cdf``, optionally including the
full filepath (e.g. ``codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf``). The filename
must be a valid IMAP filename that follows the conventions described
`here <https://imap-processing.readthedocs.io/en/latest/development-guide/style-guide/naming-conventions.html#data-product-file-naming-conventions>`_.
required: true
schema:
type: string
responses:
'302':
description: Successful download
content:
application/json:
schema:
type: array
items:
type: string
format: uri
'400':
description: Unsuccessful download
content:
application/json:
schema:
type: array
items:
type: string
format: uri

'/query':
get:
tags:
- Query
summary: Query for file metadata
operationId: query
parameters:
- in: query
name: instrument
description: |
The instrument of interest (e.g. ``mag``). Supported instruments are listed
`here <https://imap-processing.readthedocs.io/en/latest/development-guide/style-guide/naming-conventions.html#data-product-file-naming-conventions>`_.
required: false
schema:
type: string
- in: query
name: data_level
description: |
The level of data product (e.g. ``l1a``). Supported levels are listed
`here <https://imap-processing.readthedocs.io/en/latest/development-guide/style-guide/naming-conventions.html#data-product-file-naming-conventions>`_.
required: false
schema:
type: string
- in: query
name: descriptor
description: |
The descriptor of interest (e.g. ``burst``). Supported descriptors are listed
`here <https://imap-processing.readthedocs.io/en/latest/development-guide/style-guide/naming-conventions.html#data-product-file-naming-conventions>`_.
required: false
schema:
type: string
- in: query
name: start_date
description: Search for all files with a start date on or after this time, in the format ``YYYYMMDD``.
required: false
schema:
type: string
- in: query
name: end_date
description: Search for all files with a start date on or before this time, in the format ``YYYYMMDD``.
required: false
schema:
type: string
- in: query
name: version
description: The version of data product in the format ``vXX-YY`` (e.g. ``v01-01``).
required: false
schema:
type: string
- in: query
name: extension
description: The file extension of interest (e.g. ``cdf``). Supported extensions include ``pkts`` and ``cdf``.
required: false
schema:
type: string
responses:
'200':
description: Successful query
content:
application/json:
schema:
type: array
items:
type: string
format: uri
'400':
description: Unsuccessful query
content:
application/json:
schema:
type: array
items:
type: string
format: uri
6 changes: 3 additions & 3 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,9 @@ The explicit code interfaces and structure are described in the :ref:`code-docum
development-guide/index
project-management/index
external-tools/index
data-access-api/index

If you make use of any imap_processing code, please consider citing it in your research.
If you make use of any ``imap_processing`` code, please consider citing it in your research.
TODO: Add a Zenodo DOI badge here.

Contributing to IMAP
Expand Down Expand Up @@ -52,5 +53,4 @@ exploration.

Before contributing, please read through our :ref:`style-guide-overview`.

For more information on contributing to open science initiatives and to learn about tools and technologies, you can look to the NASA TOPS `Open Science 101 <https://nasa.github.io/Transform-to-Open-Science/take-os101/>`_ for free classes on Open Science and open source projects.

For more information on contributing to open science initiatives and to learn about tools and technologies, you can look to the NASA TOPS `Open Science 101 <https://nasa.github.io/Transform-to-Open-Science/take-os101/>`_ for free classes on Open Science and open source projects.
Loading
Loading