Dashboards ================== Manage the dashboards. Linked From: * :doc:`root` Dashboard Fields ---------------- .. list-table:: :header-rows: 1 :widths: 30, 70 * - Field - Description * - ``id`` - The UUID identifying the dashboard. * - ``created`` - The timestamp of when the dashboard was created in ISO8601 format. * - ``href`` - The URL used to interact with the dashboard. * - ``name`` - The name of the dashboard. Only one dashboard can have this name at given account. * - ``private`` - Controls whether or not the dashboard appears on the Contacts tab. * - ``account`` - The account the dashboard exists within. * - ``viewers`` - The URL to fetch the viewers of the dashboard. * - ``viewer_count`` - The count of viewers assigned to the dashboard. * - ``ally_count`` - The count of allies assigned to the dashboard. * - ``students`` - The URL to fetch the students of the dashboard. * - ``student_count`` - The count of students assigned to the dashboard. .. note:: To create dashboards, use the :ref:`Dashboard Upload POST ` endpoint. GET --- The ``GET`` method is used to fetch a paginated collection of dashboards. The dashboards are returned ordered by ``created`` in descending order. The ``GET`` method supports the following query string parameters: .. list-table:: :header-rows: 1 :widths: 30, 70 * - Parameter - Description * - ``cursor`` - A unique identifier to fetch the next or previous page. It is supplied in the response as a way to navigate pages. * - ``account`` - Filter down dashboards for the given account and all of its subaccounts. The account must be a subaccount of the account associated with your API token. Accepted Request Content-Types: ``application/json`` Available Response Content-Types: ``application/json`` Example Request ~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/`` Content-Type: ``application/json`` Example Success Response ~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "next": "https://apps.aspiredu.com/detective/api/v2/dashboard/?cursor=UNIQUE_STRING", "previous": "https://apps.aspiredu.com/detective/api/v2/dashboard/?cursor=DIFFERENT_UNIQUE_STRING", "results": [ { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/", "name": "Football", "private": false, "account": "AspirEDU University", "viewers": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/viewer/", "viewer_count": 10, "ally_count": 2, "students": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/student/", "student_count": 100 }, { "id": "11111111-1111-1111-1111-111111111111", "created": "2022-02-02T02:02:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/11111111-1111-1111-1111-111111111111/", "name": "Badminton", "private": false, "account": "AspirEDU University", "viewers": "https://apps.aspiredu.com/detective/api/v2/dashboard/11111111-1111-1111-1111-111111111111/viewer/", "viewer_count": 3, "ally_count": 0, "students": "https://apps.aspiredu.com/detective/api/v2/dashboard/11111111-1111-1111-1111-111111111111/student/", "student_count": 8 }, ] } PUT --- The ``PUT`` method is used to update a dashboard using all the fields. The ``PUT`` method requires the following fields: .. list-table:: :header-rows: 1 :widths: 20, 20, 60 * - Parameter - Type - Notes * - ``name`` - String - This must be unique for the account. * - ``private`` - Boolean - Private dashboards will not appear on the Contacts tab within Dropout Detective. The ``PUT`` method supports the following query string parameters: .. list-table:: :header-rows: 1 :widths: 30, 70 * - Parameter - Description * - ``account`` - Update the dashboard for the given account. The account must be a subaccount of the account associated with your API token. Accepted Request Content-Types: ``application/json`` Available Response Content-Types: ``application/json`` Example Request ~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard//`` Content-Type: ``application/json`` .. code-block:: json { "name": "New Name", "private": true } Example Success Response ~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/", "name": "New Name", "private": true, "account": "AspirEDU University", "viewers": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/viewer/", "viewer_count": 10, "ally_count": 2, "students": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/student/", "student_count": 100 } Example Error Responses ~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 404 Not Found Content-Type: ``application/json`` .. code-block:: json { "detail": "Not found." } URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 400 Bad Request Content-Type: ``application/json`` .. code-block:: json { "name": ["This field may not be blank."] } URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 400 Bad Request Content-Type: ``application/json`` .. code-block:: json { "non_field_errors": [ "The fields account, name must make a unique set." ] } PATCH ----- The ``PATCH`` method is used to update a dashboard using some of the fields. The ``PATCH`` method supports the following fields: .. list-table:: :header-rows: 1 :widths: 20, 20, 60 * - Parameter - Type - Notes * - ``name`` - String - This must be unique for the account. * - ``private`` - Boolean - Private dashboards will not appear on the Contacts tab within Dropout Detective. The ``PATH`` method supports the following query string parameters: .. list-table:: :header-rows: 1 :widths: 30, 70 * - Parameter - Description * - ``account`` - Update the dashboard for the given account. The account must be a subaccount of the account associated with your API token. Accepted Request Content-Types: ``application/json`` Available Response Content-Types: ``application/json`` Example Request ~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard//`` Content-Type: ``application/json`` .. code-block:: json { "name": "New Name", } Example Success Response ~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 200 OK Request Content-Type: ``application/json`` .. code-block:: json { "id": "00000000-0000-0000-0000-000000000000", "created": "2022-01-01T01:01:00.000000-00:00", "href": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/", "name": "New Name", "private": false, "account": "AspirEDU University", "viewers": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/viewer/", "viewer_count": 10, "ally_count": 2, "students": "https://apps.aspiredu.com/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/student/", "student_count": 100 } Example Error Responses ~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 404 Not Found Content-Type: ``application/json`` .. code-block:: json { "detail": "Not found." } URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 400 Bad Request Content-Type: ``application/json`` .. code-block:: json { "name": ["This field may not be blank."] } URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 400 Bad Request Content-Type: ``application/json`` .. code-block:: json { "non_field_errors": [ "The fields account, name must make a unique set." ] } DELETE ------ The ``DELETE`` method is used to delete a dashboard. This is irreversible. The ``DELETE`` method supports the following query string parameters: .. list-table:: :header-rows: 1 :widths: 30, 70 * - Parameter - Description * - ``account`` - Delete a dashboard for the given account. The account must be a subaccount of the account associated with your API token. Accepted Request Content-Types: ``application/json`` Available Response Content-Types: ``application/json`` Example Request ~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard//`` Content-Type: ``application/json`` Example Success Response ~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 204 No content Content-Type: ``application/json`` Example Error Response ~~~~~~~~~~~~~~~~~~~~~~~~ URL: ``/detective/api/v2/dashboard/00000000-0000-0000-0000-000000000000/`` Status: 404 Not Found Content-Type: ``application/json`` .. code-block:: json { "detail": "Not found." }