Merge pull request #316 from bourque/openapi

REST API docs via OpenAPI

docs/source/conf.py

@@ -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
@@ -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",
+    "sphinxcontrib.openapi",
     "numpydoc",
 ]
 

docs/source/data-access-api/index.rst

@@ -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>"}

docs/source/data-access-api/openapi.yml

@@ -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

docs/source/index.rst

@@ -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
@@ -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.