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:

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:

{
  "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:

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

Response:

{
  "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:

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:

{
  "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:

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:

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

Get Purpose Enums

Request:

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:

{
  "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:

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

Response:

{
  "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:

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

Response:

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

Streaming API

Status Stream

Request:

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):

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"}