REST API

The OST REST API’s support added for get entities.

Once deployed, the API should be available at <HOST>/ost/api/<MAJOR_VERSION>/<RESOURCE> and the Swagger UI at <HOST>/api/<MAJOR_VERSION>/ui. The host depends on the environment that the server is deployed to, and may include a k8s namespace - see the README for more details.

The OST API endpoints, with the accepted requests and expected responses, are documented below:

POST /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue

Create a new observing queue for a subarray with SBD items

Create a new observing queue for a subarray with SBD items.

Parameter request: The queue creation request containing subarray ID, items, and creator info. Parameter oda: UnitOfWork instance for database operations. Parameter queue_service: Injected queue service for business logic operations. Returns: The API response with created queue data. Raises ValidationError: If SBD conflicts exist or targets are not visible. Raises ValidationError: Target source is not visible. Raises ValidationError: SBD not present in ODA. Raises QueueCreationError: If queue creation fails in the service layer.

Request Headers:

  • X-Request-ID

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue/{queue_id}/subarray/{subarray_id}

Get observing queue by queue_id and subarray_id

Retrieve a specific queue by queue ID and subarray ID.

Parameter queue_id: The unique identifier of the queue to retrieve. Parameter subarray_id: The subarray ID to filter the queue. Parameter queue_service: Injected queue service for business logic operations. Returns: The API response with queue data and items. Returns empty array with 200 status if queue not found or invalid ID.

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • subarray_id (integer, required)

Status Codes:
PUT /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue/{queue_id}/subarray/{subarray_id}

Replace all items in an observing queue

Replace all items in an existing queue with new SBD items.

Parameter queue_id: The unique identifier of the queue to update. Parameter subarray_id: The subarray ID for validation. Parameter request: The update request containing new items and modifier info. Parameter oda: UnitOfWork instance for database operations. Parameter queue_service: Injected queue service for business logic operations. Raises ValidationError: If SBD conflicts exist or targets are not visible. Raises ValidationError: Target source is not visible. Raises ValidationError: SBD not present in ODA. Returns: The API response with updated queue data. Returns empty array with 200 status if queue not found or invalid ID.

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • subarray_id (integer, required)

Status Codes:
DELETE /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue/{queue_id}/subarray/{subarray_id}

Delete observing queue and all its items

Delete a queue and all its items.

Parameter queue_id: The unique identifier of the queue to delete. Parameter subarray_id: The subarray ID for validation. Parameter queue_service: Injected queue service for business logic operations. Returns: The API response confirming deletion. Raises HTTPException: If queue not found (404) or deletion fails (500).

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • subarray_id (integer, required)

Status Codes:
PATCH /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue/{queue_id}/subarray/{subarray_id}

Patch queue by adding or updating specific SBD items

Patch queue by adding or updating specific SBD items.

Parameter queue_id: The unique identifier of the queue to patch. Parameter subarray_id: The subarray ID for validation. Parameter request: The patch request containing items to add or update. Parameter oda: UnitOfWork instance for database operations. Parameter queue_service: Injected queue service for business logic operations. Raises ValidationError: If SBD conflicts exist or targets are not visible. Raises ValidationError: Target source is not visible. Raises ValidationError: SBD not present in ODA. Returns: The API response with patched queue data. Returns empty array with 200 status if queue not found or invalid ID.

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • subarray_id (integer, required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue/subarray/{subarray_id}

Get all observing queues by subarray_id

Retrieve all queues for a subarray.

Parameter subarray_id: The subarray ID to filter queues. Parameter queue_service: Injected queue service for business logic operations. Returns: The API response with first queue data and items. Raises HTTPException: If no queues found (404) or validation errors (400).

Request Headers:

  • X-Request-ID

Parameters:

  • subarray_id (integer, required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue/{queue_id}/subarray/{subarray_id}/current

Get currently executing item from observing queue

Get the queue with currently executing SBD items.

Parameter queue_id: The unique identifier of the queue. Parameter subarray_id: The subarray ID for validation. Parameter queue_service: Injected queue service for business logic operations. Returns: The API response with queue containing executing items. Returns empty array with 200 status if not found.

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • subarray_id (integer, required)

Status Codes:
DELETE /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue/{queue_id}/subarray/{subarray_id}/items/{item_id}

Delete a specific item from the observing queue

Delete a specific item from a queue.

Parameter queue_id: The unique identifier of the queue. Parameter subarray_id: The subarray ID for validation. Parameter item_id: The ID of the item to delete. Parameter queue_service: Injected queue service for business logic operations. Returns: The API response confirming item deletion. Raises HTTPException: If queue/item not found (404) or deletion fails (500).

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • subarray_id (integer, required)

  • item_id (string, required)

Status Codes:
PUT /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue_items/{item_id}/queue/{queue_id}

Updates queue item in an observing queue

Update queue items in the observing queue.

Parameter queue_id: The unique identifier of the queue to update. Parameter item_id: The item ID of queue item. Parameter item: The update request containing updated items data. Parameter queue_service: Injected queue service for business logic operations. Raises ValidationError: If SBD conflicts exist or targets are not visible. Raises ValidationError: Target source is not visible. Raises ValidationError: SBD not present in ODA. Returns: The API response with updated queue data. Returns empty array with 200 status if queue not found or invalid ID.

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • item_id (string, required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/observing_queue_items/{item_id}/queue/{queue_id}

Get Queue item info

Get the queue item.

Parameter queue_id: The unique identifier of the queue. Parameter item_id: The item ID to retrieve queue item. Parameter queue_service: Injected queue service for business logic operations. Returns: The API response with queue containing executing items. Returns empty array with 200 status if not found.

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (string, required)

  • item_id (string, required)

Status Codes:
POST /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/oet/{queue_id}/{subarray_id}/start

Start queue execution on subarray

Start execution of queue items on a subarray via OET.

Items are executed sequentially, with real-time updates sent via WebSocket.

Parameter queue_id: The unique identifier of the queue to execute. Parameter subarray_id: The subarray ID for validation and execution. Parameter oet_tasks: FastAPI background tasks for async execution. Parameter queue_service: Injected queue service for business logic operations. Parameter oet_service: Injected OET service for execution operations. Returns: The API response confirming execution start. Raises HTTPException: If queue not found (404) or execution fails (500).

Request Headers:

  • X-Request-ID

Parameters:

  • queue_id (required)

  • subarray_id (required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/oet/stream

Stream Queue Execution

Real-time SSE stream of queue execution status.

This endpoint provides Server-Sent Events (SSE) streaming of real-time execution status for all OET instances. Clients can connect to receive live updates about queue progress, item completion, and errors.

Event Types: - QUEUE_STARTED: Queue execution begins - ITEM_STARTED: Individual item execution begins - PROGRESS_UPDATE: Item progress update (every 2 seconds) - ITEM_FINISHED: Item execution completes - QUEUE_FINISHED: Queue execution completes - QUEUE_ERROR: Queue execution error

Example Event:

data: {
    "timestamp": "2024-01-01T10:00:00Z",
    "data": {
        "oet_instance_1": {
            "queue": {
                "queue_id": "queue_1",
                "status": "RUNNING",
                "progress_percentage": 45.5,
                "total_items": 10,
                "completed_items": 4,
                "failed_items": 1,
                "running_items": 1
            },
            "items": [...]
        }
    }
}

Parameter request: FastAPI request object for disconnect detection Parameter streaming_service: Injected streaming service Returns: SSE stream with real-time updates Return type: StreamingResponse

Request Headers:

  • X-Request-ID

Status Codes:
PUT /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/oet/{subarray_id}/abort

Abort queue execution on subarray

Abort execution of queue items on a subarray via OET.

Parameter procedure_id: The unique identifier of the procedure to abort. Parameter oet_service: Injected OET service for execution operations. Returns: The API response confirming execution start.

Request Headers:

  • X-Request-ID

Parameters:

  • subarray_id (string, required)

Status Codes:
PUT /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/oet/{queue_id}/{subarray_id}/stop

Stop queue execution on subarray

stop queue execution of queue items on a subarray via OET.

Parameter queue_id: The unique identifier of the queue to execute. Parameter subarray_id: The subarray ID for validation and execution. Parameter oet_tasks: FastAPI background tasks for async execution. Parameter queue_service: Injected queue service for business logic operations. Parameter oet_service: Injected OET service for execution operations. Returns: The API response confirming execution start. Raises HTTPException: If queue not found (404) or execution fails (500).

Request Headers:

  • X-Request-ID

Parameters:

  • subarray_id (integer, required)

  • queue_id (string, required)

Status Codes:
POST /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/scheduler/confirmations/{sbd_fk}/confirm

Confirm Execution

Confirm execution of a scheduled item by sbd_fk.

Parameter sbd_fk: SBD reference string Returns: Confirmation message dictionary Raises HTTPException: If confirmation not found (404) or execution fails (500)

Request Headers:

  • X-Request-ID

Parameters:

  • sbd_fk (string, required)

Status Codes:
POST /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/scheduler/confirmations/{sbd_fk}/override

Override And Execute

Override validation and force execution (operator override).

Parameter sbd_fk: SBD reference string Returns: Override confirmation message dictionary Raises HTTPException: If confirmation not found (404)

Request Headers:

  • X-Request-ID

Parameters:

  • sbd_fk (string, required)

Status Codes:
POST /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/scheduler/confirmations/{sbd_fk}/reject

Reject Execution

Reject execution of a scheduled item by sbd_fk.

Parameter sbd_fk: SBD reference string Returns: Rejection message dictionary Raises HTTPException: If confirmation not found (404)

Request Headers:

  • X-Request-ID

Parameters:

  • sbd_fk (string, required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/sbds

Get All SB Definition with status appended, filter by the query parameter like created_before, created_after and user namer

Function that a GET /sbds request is routed to.

Parameter query_params: Parameters to query the ODA by. Returns: All SBDefinitions present with status wrapped in a Response, or appropriate error Response

Request Headers:

  • X-Request-ID

Query Parameters:

  • user

  • match_type

  • query_type

  • created_before

  • created_after

  • last_modified_before

  • last_modified_after

  • entity_id

  • purpose

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/sbds/{sbd_id}

Get specific SB Definition by identifier with status appended

Function that a GET /sbds/<sbd_id> request is routed to.

Parameter oda: Unit of Work for database operations. Parameter sbd_id: Requested identifier from the path parameter Returns: The SBDefinition with status wrapped in a Response, or appropriate error Response Return type: ApiResponse[SBDefinitionStatusModel]

Request Headers:

  • X-Request-ID

Parameters:

  • sbd_id (string, required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/ebs

Get All Execution Block with status appended, filter by the query parameter like created_before, created_after and user name

Function that a GET /ebs request is routed to.

Parameter oda: Unit of Work for database operations. Parameter query_params: Parameters to query the ODA by. Returns: All ExecutionBlocks present with status wrapped in a Response, or appropriate error Response Return type: ApiResponse[EBStatusModel]

Request Headers:

  • X-Request-ID

Query Parameters:

  • user

  • match_type

  • query_type

  • created_before

  • created_after

  • last_modified_before

  • last_modified_after

  • entity_id

  • purpose

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/ebs/{eb_id}

Get specific Execution Block by identifier with status appended

Function that a GET /ebs/<eb_id> request is routed to.

Parameter oda: Unit of Work for database operations. Parameter eb_id: Requested identifier from the path parameter Returns: The ExecutionBlock with status wrapped in a Response, or appropriate error Response Return type: ApiResponse[EBStatusModel]

Request Headers:

  • X-Request-ID

Parameters:

  • eb_id (string, required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/prjs/{prj_id}

Get specific Project by identifier with status appended

Function that a GET /prjs/<prj_id> request is routed to.

Parameter oda: Unit of Work for database operations. Parameter prj_id: Requested identifier from the path parameter Returns: The Project with status wrapped in a Response, or appropriate error Response Return type: ApiResponse[ProjectStatusModel]

Request Headers:

  • X-Request-ID

Parameters:

  • prj_id (string, required)

Status Codes:
GET /dev-ska-oso-ost-services-nak-1747-move-oda-rest-layer/ost/api/v1/sbis/{sbi_id}

Get specific SB Instance by identifier with status appended

Function that a GET /sbis/<sbi_id> request is routed to.

Parameter oda: Unit of Work for database operations. Parameter sbi_id: Requested identifier from the path parameter Returns: The SBInstance with status wrapped in a Response, or appropriate error Response Return type: ApiResponse[SBInstanceStatusModel]

Request Headers:

  • X-Request-ID

Parameters:

  • sbi_id (string, required)

Status Codes: