REST API

The ODA REST API supports resources for SBDefinitions, SBInstances, ExecutionBlocks and Projects. Each resource supports a GET and PUT method as documented below. There is also a general end point which will support PUT for multiple resources as an atomic operation.

Additionally, there are custom Execution Block resources. For more context, see ODA Helper Module.

Once deployed, the API should be available at <HOST>/api/v1/<RESOURCE> and the Swagger UI at <HOST>/api/v1/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. For example, to retrieve SBDefinition sbd-mvp01-20200325-00001 from the staging environment, the request would be

$ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/api/v1/sbds/sbd-mvp01-20200325-00001"

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

PUT /

Store multiple entities

Stores the entities as an atomic operation.

Status Codes:
GET /sbds

Get SBDefinition IDs filter by the query parameter

Retrieves the IDs of the SBDefinitions which match the query parameters. Currently only a single query field is permitted, eg user or created_on - extra parameters passed to the request will be ignored, with an order of precedence of user > created_on > modified_on. Also requests without parameters will return an error rather than returning all IDs. This behaviour will change in the future

Query Parameters:

  • user (string) –

  • user_match_type (string) –

  • created_before (string) –

  • created_after (string) –

  • last_modified_before (string) –

  • last_modified_after (string) –

Status Codes:
POST /sbds

Create a new SBDefinition

Stores the SBDefinition in the underlying data store, with an identifier generated from SKUID

Status Codes:
GET /sbds/{sbd_id}

Get SBDefiniton by identifier

Retrieves the SBDefinition with the given identifier from the underlying data store, if available

Parameters:

  • sbd_id (string) –

Status Codes:
PUT /sbds/{sbd_id}

Store SBDefinition by identifier

Stores the SBDefinition with the given identifier in the underlying data store. If the identifier does not exist in the data store, a new version 1 will be created. If a version does exist, an update will be performed. In this case, the metadata in the recieved SBDefinition should match the existing version - the user of this API should not edit metadata before sending.

Parameters:

  • sbd_id (string) –

Status Codes:
GET /sbis

Get SBInstance IDs filter by the query parameter

Retrieves the IDs of the SBInstances which match the query parameters. Currently only a single query field is permitted, eg user or created_on - extra parameters passed to the request will be ignored, with an order of precedence of user > created_on > modified_on. Also requests without parameters will return an error rather than returning all IDs. This behaviour will change in the future

Query Parameters:

  • user (string) –

  • user_match_type (string) –

  • created_before (string) –

  • created_after (string) –

  • last_modified_before (string) –

  • last_modified_after (string) –

Status Codes:
POST /sbis

Create a new SBInstance

Stores the SBInstance in the underlying data store, with an identifier generated from SKUID

Status Codes:
GET /sbis/{sbi_id}

Get SBInstance by identifier

Retrieves the SBInstance with the given identifier from the underlying data store, if available

Parameters:

  • sbi_id (string) –

Status Codes:
PUT /sbis/{sbi_id}

Store SBInstance by identifier

Stores the SBInstance with the given identifier in the underlying data store. If the identifier does not exist in the data store, a new version 1 will be created. If a version does exist, an update will be performed. In this case, the metadata in the recieved SBInstance should match the existing version - the user of this API should not edit metadata before sending.

Parameters:

  • sbi_id (string) –

Status Codes:
GET /ebs

Get ExecutionBlock IDs filter by the query parameter

Retrieves the IDs of the ExecutionBlocks which match the query parameters. Currently only a single query field is permitted, eg user or created_on - extra parameters passed to the request will be ignored, with an order of precedence of user > created_on > modified_on. Also requests without parameters will return an error rather than returning all IDs. This behaviour will change in the future

Query Parameters:

  • user (string) –

  • user_match_type (string) –

  • created_before (string) –

  • created_after (string) –

  • last_modified_before (string) –

  • last_modified_after (string) –

Status Codes:
POST /ebs

Create a new ExecutionBlock

Stores the ExecutionBlock in the underlying data store, with an identifier generated from SKUID

Status Codes:
GET /ebs/{eb_id}

Get ExecutionBlock by identifier

Retrieves the ExecutionBlock with the given identifier from the underlying data store, if available

Parameters:

  • eb_id (string) –

Status Codes:
PUT /ebs/{eb_id}

Store ExecutionBlock by identifier

Stores the ExecutionBlock with the given identifier in the underlying data store. If the identifier does not exist in the data store, a new version 1 will be created. If a version does exist, an update will be performed. In this case, the metadata in the recieved ExecutionBlock should match the existing version - the user of this API should not edit metadata before sending.

Parameters:

  • eb_id (string) –

Status Codes:
PATCH /ebs/{eb_id}/request_response

Add a record to the Execution Block

Adds the record of the function called on the telescope and its response to the Execution Block with the given eb_id. The purpose of this resource as opposed to the generic update of a whole entity is that user of the scripting functions can record these functions and the responses without having to know the internals of the ODA or the Execution Block data structure.

Parameters:

  • eb_id (string) –

Status Codes:
GET /prjs

Get Project IDs filter by the query parameter

Retrieves the IDs of the Projects which match the query parameters. Currently only a single query field is permitted, eg user or created_on - extra parameters passed to the request will be ignored, with an order of precedence of user > created_on > modified_on. Also requests without parameters will return an error rather than returning all IDs. This behaviour will change in the future

Query Parameters:

  • user (string) –

  • user_match_type (string) –

  • created_before (string) –

  • created_after (string) –

  • last_modified_before (string) –

  • last_modified_after (string) –

Status Codes:
POST /prjs

Create a new Project

Stores the Project in the underlying data store, with an identifier generated from SKUID

Status Codes:
GET /prjs/{prj_id}

Get Project by identifier

Retrieves the Project with the given identifier from the underlying data store, if available

Parameters:

  • prj_id (string) –

Status Codes:
PUT /prjs/{prj_id}

Store Project by identifier

Stores the Project with the given identifier in the underlying data store. If the identifier does not exist in the data store, a new version 1 will be created. If a version does exist, an update will be performed. In this case, the metadata in the recieved Project should match the existing version - the user of this API should not edit metadata before sending.

Parameters:

  • prj_id (string) –

Status Codes: