From 8222c1b9ebf850b139baf8d8847abeea33310345 Mon Sep 17 00:00:00 2001
From: anamanica <ana@manica.org>
Date: Wed, 7 Aug 2024 15:44:47 -0600
Subject: [PATCH] Data access api (#720)

* Making the Data Access API documentation clearer, and updating information.
---
 docs/source/data-access-api/index.rst   | 18 ++++++++++++++++--
 docs/source/data-access-api/openapi.yml |  4 +++-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/docs/source/data-access-api/index.rst b/docs/source/data-access-api/index.rst
index 3daf1d246..57cbc6bed 100644
--- a/docs/source/data-access-api/index.rst
+++ b/docs/source/data-access-api/index.rst
@@ -11,14 +11,21 @@ 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
-
+*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
 
 .. openapi:: openapi.yml
    :group:
    :include: /upload
 
+When uploading files to the API, ensure these files are stored properly in a ``data`` directory. Then,
+ensure your working directory is one level above the ``data`` directory in order to properly upload files.
+
+[WIP] Certain ancillary files can also be uploaded to the API. For more specific information regarding these files, visit
+`Ancillary Files <https://imap-processing.readthedocs.io/en/latest/data-access-api/calibration-files.html>`_
+
 **Example Usage:**
 
 .. code-block:: bash
@@ -45,6 +52,13 @@ The API can be accessed from the following URL: https://api.dev.imap-mission.com
    :group:
    :include: /download
 
+It is important to note that your working directory will be established as the default directory. I.e, the ``data``
+directory--which files are downloaded to--will automatically be placed in this file path. Choose your working directory
+accordingly to suit your desires.
+
+When downloading a file from the API, different folders within the ``data`` directory will be made to better
+organize the files. See the example file path: ``data/imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_20240105_v00-01.pkts``
+
 **Example Usage:**
 
 .. code-block:: bash
diff --git a/docs/source/data-access-api/openapi.yml b/docs/source/data-access-api/openapi.yml
index bc2ba78be..18952ed46 100644
--- a/docs/source/data-access-api/openapi.yml
+++ b/docs/source/data-access-api/openapi.yml
@@ -52,6 +52,7 @@ paths:
                 items:
                   type: string
 
+
   '/download/{filepath}':
     get:
       tags:
@@ -143,7 +144,8 @@ paths:
             type: string
         - in: query
           name: version
-          description: The version of data product in the format ``vXX-YY`` (e.g. ``v01-01``).
+          description: The version of data product in the format ``vNNN`` (e.g. ``v001``). You can also choose to
+            query ``--version latest`` in order to receive the most recent version of a file.
           required: false
           schema:
             type: string