.. _backend_api:

Open edX Backend: API reference
===============================

.. contents:: On this page
   :local:
   :depth: 2

The backend exposes a small REST API under ``/panorama/api/`` on the LMS. All endpoints
require an authenticated session (they use the LMS JWT / session auth), and the MFE calls them
with the authenticated HTTP client. Responses are JSON objects of the shape
``{"statusCode": <n>, "body": <payload>}``.

.. list-table::
   :header-rows: 1
   :widths: 26 12 62

   * - Path
     - Method
     - Purpose
   * - ``get-panorama-mode``
     - GET
     - Returns the configured mode (``DEMO`` / ``FREE`` / ``SAAS`` / ``CUSTOM``). The MFE uses
       it to choose the home page.
   * - ``get-user-access``
     - GET
     - Returns a boolean: whether the current user may access Panorama (see the access rules
       in :ref:`backend_modes`).
   * - ``get-user-role``
     - GET
     - Returns the user's role (``READER``, ``AUTHOR``, ``STUDENT``, or none), which the MFE
       uses to decide what to render.
   * - ``get-embed-url``
     - GET
     - Returns the list of dashboards for the user, each with a short-lived embed URL. The
       source depends on the mode.
   * - ``get-studio-url``
     - GET
     - Returns a QuickSight **console** (authoring) embed URL. Used by the Studio tab for
       ``AUTHOR`` users.

``get-embed-url`` behavior by mode
----------------------------------

The dashboard endpoint resolves differently per :ref:`mode <backend_modes>`:

* **DEMO** — fetches demo dashboards from Aulasneo's demo API (rejects local/dev hosts and
  non-HTTPS).
* **FREE** — fetches free dashboards from Aulasneo's Panorama API using SigV4-signed requests.
* **SAAS** — fetches SaaS dashboards from Aulasneo's Panorama API using SigV4-signed requests.
* **CUSTOM** — generates embed URLs directly from your QuickSight account for the user's
  assigned dashboards.

Each returned dashboard has ``name``, ``displayName``, ``id``, and ``url``. For student-view
dashboards the ``url`` fragment carries the ``userId``, ``userFullName``, and ``lms``
parameters.

Error handling
--------------

* If ``HTTPS`` is not ``'on'``, ``get-embed-url`` returns HTTP **421** ("HTTP not supported.
  Use only HTTPS.").
* Configuration problems in ``CUSTOM`` mode surface as errors such as *Unassigned user ARN*,
  *Dashboard not assigned to user*, or *User role not assigned*.
* ``get-studio-url`` returns HTTP 400 if the user has no QuickSight ARN, and 500 on QuickSight
  / boto errors.

`Back to Home <index.html>`_