API Request and Response Examples
=================================

This document provides detailed examples of API requests and responses for the PTT services.

Status Management APIs
----------------------

Get Latest Status Entries
~~~~~~~~~~~~~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   GET /ska-oso-ptt-services/ptt/api/v1/entity/latest/status?entity_id=eb-rftkroa3-20260131-950503814821162 HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>

**Response:**

.. code-block:: json

   {
     "result_data": [
       {
         "entity_id": "eb-a0n7rsm5r2e",
         "status": "Fully Observed",
         "updated_by": "user1",
         "as_of": "2024-01-01T11:00:00Z"
       }
     ],
     "result_status": "OK",
     "result_code": 200
   }

Get Current Status View
~~~~~~~~~~~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   GET /ska-oso-ptt-services/ptt/api/v1/entity/current/status HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>

**Response:**

.. code-block:: json

   {
     "result_data": [
       {
         "entity_id": "eb-a0n7rsm5r2e",
         "status": "Fully Observed",
         "updated_by": "user1",
         "as_of": "2024-01-01T11:00:00Z"
       },
       {
         "entity_id": "sbi-a1583be5st5",
         "status": "Observed",
         "updated_by": "system",
         "as_of": "2024-01-01T10:30:00Z"
       }
     ],
     "result_status": "OK",
     "result_code": 200
   }

Update Entity Status
~~~~~~~~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   PUT /ska-oso-ptt-services/ptt/api/v1/entity/eb-rftkroa3-20260131-950503814821162/status?status=Fully%20Observed HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>

**Response:**

.. code-block:: json

   {
     "result_data": {
       "entity_id": "eb-a0n7rsm5r2e",
       "status": "Fully Observed",
       "updated_by": "user1",
       "as_of": "2024-01-01T11:00:00Z"
     },
     "result_status": "OK",
     "result_code": 200
   }

Get Entity Status Dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   GET /ska-oso-ptt-services/ptt/api/v1/entity/status/get_entity?entity_name=eb HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>

**Response:**

.. code-block:: json

   {
     "result_data": {
       "entity_type": "eb",
       "statuses": {
         "CREATED": "Created",
         "FULLY_OBSERVED": "Fully Observed",
         "FAILED": "Failed"
       }
     },
     "result_status": "OK",
     "result_code": 200
   }

Get Purpose Enums
~~~~~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   GET /ska-oso-ptt-services/ptt/api/v1/entity/status/get_entity?is_purpose=true HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>

**Response:**

.. code-block:: json

   {
     "result_data": {
       "SCIENCE": "Science",
       "ENGINEERING": "Engineering",
       "COMMISSIONING": "Commissioning",
       "CALIBRATION": "Calibration"
     },
     "result_status": "OK",
     "result_code": 200
   }

Project Management APIs
-----------------------

Get Projects with Purpose Filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   GET /ska-oso-ptt-services/ptt/api/v2/prjs?purpose=Science HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>

**Response:**

.. code-block:: json

   {
     "result_data": [
       {
         "prj_id": "prj-a15834w5s7k",
         "name": "SKA Mid Project",
         "purpose": "Science",
         "obs_block":[{
                      "name": "Block 1",
                      "obs_block_id": "ob-1"
         }],
         "status": "Ready",
         "metadata": {
           "created_by": "TestUser",
           "created_on": "2022-09-23T15:43:53.971548Z"
         }
       }
     ],
     "result_status": "success",
     "result_code": 200
   }

Get Dashboard with Purpose Filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   GET /ska-oso-ptt-services/ptt/api/v2/dashboard?purpose=Commissioning HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>

**Response:**

.. code-block:: json

   {
     "result_data": {
       "projects": [
         {
           "prj_id": "prj-a15834w5s7k",
           "purpose": "Commissioning",
           "status": "In Progress"
         }
       ]
     },
     "result_status": "success",
     "result_code": 200
   }

Streaming API
-------------

Status Stream
~~~~~~~~~~~~~

**Request:**

.. code-block:: http

   GET /ska-oso-ptt-services/ptt/api/v1/status/stream HTTP/1.1
   Host: api.example.com
   Authorization: Bearer <token>
   Accept: text/event-stream

**Response (Server-Sent Events):**

.. code-block:: text

   data: {"type": "connected"}

   data: {"entity_id": "eb-a0n7rsm5r2e", "status": "Executing", "updated_by": "user1", "timestamp": "2024-01-01T11:00:00Z"}

   data: {"type": "heartbeat"}

   data: {"entity_id": "eb-a0n7rsm5r2e", "status": "Observed", "updated_by": "system", "timestamp": "2024-01-01T11:05:00Z"}