REST API docs via OpenAPI

docs/source/conf.py

@@ -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,63 @@
+.. _sdc-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
+
+**Example Usage:**
+
+.. code-block:: bash
+
+   curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/upload/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" https://api.dev.imap-mission.com/download?s3_uri=s3://sds-data/imap/codice/l1a/2026/01/imap_codice_l1a_lo_20260101_20260102_v01-01.cdf
+
+**Possible Responses:**
+
+.. code-block:: json
+
+   {"statusCode": 302, "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?mission=imap&level=l0&instrument=mag&date=20230112&version=*&extension=pkts
+
+**Possible Responses:**
+
+.. code-block:: json
+
+   {"statusCode": 200, "body": {"mission": "imap", "level": "l0", "instrument": "mag", "date": "20230112", "version": "*", "extension": "pkts"}}

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

@@ -0,0 +1,156 @@
+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/{filename}':
+    get:
+      tags:
+        - Upload
+      summary: Upload a file to the SDC
+      operationId: upload_file
+      parameters:
+        - name: filename
+          in: path
+          required: true
+          description: |
+            The filename to upload. 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>`_,
+            *e.g.* ``imap_codice_l1a_lo_20260101_20260102_v01-01.cdf``
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful upload
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  format: uri
+                  example: 's3://bucket-name/filepath/filename.pkts'
+        '400':
+          description: Invalid or missing filename
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  example: 'A pre-signed URL could not be generated. Please ensure that the file name matches mission file naming conventions.'
+
+
+  '/download/{filename_uri}':
+    get:
+      tags:
+        - Download
+      summary: Download files from the SDC
+      operationId: download
+      parameters:
+        - in: path
+          name: s3_uri
+          description: The filename to download from the S3 bucket (i.e. ``s3://{bucket_name}/{filepath}/{filename}``)
+          required: true
+          schema:
+            type: string
+      responses:
+        '302':
+          description: Successful download
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  format: uri
+                  example: '{"download_url": "{pre_signed_url}"}'
+        '400':
+          description: Unsuccessful download
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  format: uri
+                  example: 'Not a valid S3 URI.  Example input: s3://bucket/path/file.ext'
+
+  '/query':
+    get:
+      tags:
+        - Query
+      summary: Query for file metadata
+      operationId: query
+      parameters:
+        - in: query
+          name: mission
+          description: The mission of interest (currently only ``imap`` is supported)
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: level
+          description: |
+            The level of data product (e.g. ``l1a``), or ``*`` for all levels. 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: instrument
+          description: |
+            The instrument of interest (e.g. ``mag``), or ``*`` for all instruments. 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: date
+          description: The date of observation in the format ``YYYYMMDD``, or ``*`` for all dates.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: version
+          description: The version of data product in the format ``vXX-YY`` (e.g. ``v01-01``), or ``*`` for all versions.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: extension
+          description: |
+            The file extension of interest (e.g. ``pkts``), or ``*`` for all extensions. 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
+                  example: {
+                    "_index": "test_data",
+                    "_type": "_doc",
+                    "_id": "1",
+                    "_score": 0.2876821,
+                    "_source": {
+                      "mission": "imap",
+                      "level": "l0",
+                      "instrument": "mag",
+                      "date": "20230112",
+                      "version": "*",
+                      "extension": "pkts",
+                  },
+            }

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.