Documentation for SPICE queries (#3005)

* added spice documentation

* replaced dev api endoints in docs with prod api endoints

* Update docs/source/data-access/openapi.yml

---------

Co-authored-by: Tim Plummer <timothy.plummer@lasp.colorado.edu>

Author: vineetbansal

docs/source/data-access/index.rst

@@ -11,14 +11,15 @@ interacting with the API programmatically. It is the preferred way to use the AP
     :maxdepth: 1
 
     imap-data-access
+    spice-files
 
 Users may also download, upload, and query via the REST API directly through the browser, or via `curl` commands.
 The `REST API Specification`_ section describes the various endpoints that are supported, and how to use them.
 
 *Note: Several sections and links begin with* [WIP]. *As development on the API is ongoing, this indicates
 that the full implementation of the functionality is yet to be completed.*
 
-The API can be accessed from the following URL [WIP]: https://api.dev.imap-mission.com
+The API can be accessed from the following URL [WIP]: https://api.imap-mission.com
 
 Command Line Utility
 --------------------
@@ -162,7 +163,7 @@ for example, with ``IMAP_DATA_DIR=/data:``
 Data Access URL
 ^^^^^^^^^^^^^^^
 
-To change the default URL that the package accesses, you can set the environment variable ``IMAP_DATA_ACCESS_URL`` or within the package ``imap_data_access.config["DATA_ACCESS_URL"]``. The default is the development server (``https://api.dev.imap-mission.com``).
+To change the default URL that the package accesses, you can set the environment variable ``IMAP_DATA_ACCESS_URL`` or within the package ``imap_data_access.config["DATA_ACCESS_URL"]``. The default is the production server (``https://api.imap-mission.com``).
 
 File Validation
 ---------------
@@ -227,7 +228,7 @@ REST API Specification
 
     .. code-block:: bash
 
-       curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/upload/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts
+       curl -X GET -H "Accept: application/json" https://api.imap-mission.com/upload/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts
 
 **Possible Responses:**
 
@@ -252,7 +253,7 @@ REST API Specification
 
 .. code-block:: bash
 
-   curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/download/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts
+   curl -X GET -H "Accept: application/json" https://api.imap-mission.com/download/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts
 
 **Possible Responses:**
 
@@ -270,7 +271,7 @@ REST API Specification
 
 .. code-block:: bash
 
-   curl -X GET -H "Accept: application/json" https://api.dev.imap-mission.com/query?instrument=swe&data_level=l0&descriptor=sci&start_date=20240105&end_date=20240105&extension=pkts
+   curl -X GET -H "Accept: application/json" https://api.imap-mission.com/query?instrument=swe&data_level=l0&descriptor=sci&start_date=20240105&end_date=20240105&extension=pkts
 
 **Possible Responses:**
 

docs/source/data-access/openapi.yml

@@ -1,7 +1,7 @@
 openapi: 3.0.0
 servers:
-  - description: Development IMAP SDC Server
-host: https://api.dev.imap-mission.com/
+  - description: Production IMAP SDC Server
+host: https://api.imap-mission.com/
 info:
   version: "0.1.0"
   title: IMAP SDC API
@@ -229,4 +229,181 @@ paths:
                 type: array
                 items:
                   type: string
-                  format: uri
+                  format: uri
+
+  '/spice-query':
+    get:
+      tags:
+        - SPICE Query
+      summary: Query for SPICE kernel metadata
+      operationId: spice-query
+      parameters:
+        - in: query
+          name: file_name
+          description: |
+            The name of a specific SPICE kernel file (e.g. ``naif0012.tls``).
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: start_time
+          description: |
+            Coverage start time in TDB seconds since J2000. Returns kernels whose
+            coverage ends on or after this time.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: end_time
+          description: |
+            Coverage end time in TDB seconds since J2000. Returns kernels whose
+            coverage begins on or before this time.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: type
+          description: |
+            The SPICE kernel type to filter by. Accepted values are:
+            ``leapseconds``, ``planetary_constants``, ``imap_frames``,
+            ``science_frames``, ``spacecraft_clock``, ``earth_attitude``,
+            ``planetary_ephemeris``, ``ephemeris_reconstructed``,
+            ``ephemeris_nominal``, ``ephemeris_predicted``, ``ephemeris_90days``,
+            ``ephemeris_long``, ``ephemeris_launch``, ``attitude_history``,
+            ``attitude_predict``, ``pointing_attitude``.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: latest
+          description: |
+            If ``True``, only return the latest version of each kernel matching
+            the other query parameters.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: start_ingest_date
+          description: |
+            Filter results to kernels ingested on or after this date, in the
+            format ``YYYYMMDD``.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: end_ingest_date
+          description: |
+            Filter results to kernels ingested on or before this date, in the
+            format ``YYYYMMDD``.
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful query — returns a list of SPICE kernel metadata objects
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+        '400':
+          description: Invalid query parameter or parameter value
+          content:
+            application/json:
+              schema:
+                type: string
+
+  '/metakernel':
+    get:
+      tags:
+        - SPICE Query
+      summary: Retrieve a metakernel or list of SPICE kernel filenames for a time range
+      operationId: metakernel
+      parameters:
+        - in: query
+          name: start_time
+          description: |
+            Coverage start time. Accepts either TDB seconds since J2000 or a date
+            string in the format ``YYYYMMDD``.
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: end_time
+          description: |
+            Coverage end time. Accepts either TDB seconds since J2000 or a date
+            string in the format ``YYYYMMDD``.
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: spice_path
+          description: |
+            Root path for the SPICE directory. This path is prepended to all kernel file
+            locations in the returned metakernel. If omitted the paths are left
+            relative. Only applicable if ``list_files``` is ``False``.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: list_files
+          description: |
+            If ``True``, return only a list of kernel filenames instead of a full
+            metakernel file.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: require_coverage
+          description: |
+            If ``True``, the request will fail with a HTTP ``422`` status if there
+            are any gaps in coverage for the requested time range.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: file_types
+          description: |
+            Comma-separated list of kernel types to include. If omitted, all
+            available kernel types are included. Accepted values are:
+            ``leapseconds``, ``planetary_constants``, ``imap_frames``,
+            ``science_frames``, ``spacecraft_clock``, ``earth_attitude``,
+            ``planetary_ephemeris``, ``ephemeris_reconstructed``,
+            ``ephemeris_nominal``, ``ephemeris_predicted``, ``ephemeris_90days``,
+            ``ephemeris_long``, ``ephemeris_launch``, ``attitude_history``,
+            ``attitude_predict``, ``pointing_attitude``.
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: |
+            Successful response. Returns a metakernel file (text/plain) when
+            ``list_files`` is ``False`` (default), or a JSON array of kernel
+            filenames when ``list_files`` is ``True``.
+          content:
+            text/plain:
+              schema:
+                type: string
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+        '404':
+          description: No kernel files found for the requested time range
+          content:
+            application/json:
+              schema:
+                type: string
+        '422':
+          description: |
+            Coverage gaps detected when ``require_coverage=True``. The response
+            body contains a list of the gap intervals.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object