REST API
The ODA REST API supports resources for SBDefinitions, SBInstances, ExecutionBlocks and Projects. Each resource supports a POST method to create a new entity, which will fetch a new identifier from SKUID. There are also GET and PUT method for a resource identifier to retrieve and update the entity, retrospectively. 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>/oda/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. 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/oda/api/<MAJOR_VERSION>/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:
200 OK – OK
400 Bad Request – Bad Request, validation of against OpenAPI spec failed
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- GET /sbds
Get SBDefinition filter by the query parameter
Retrieves the SBDefinitions which match the query parameters. Currently only a single query field is permitted, eg user, entity_id 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 objects. This behaviour will change in the future..
- Query Parameters:
user (string) –
match_type (string) –
created_before (string) –
created_after (string) –
last_modified_before (string) –
last_modified_after (string) –
entity_id (string) –
- Status Codes:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
500 Internal Server Error – Internal Server Error
- POST /sbds
Create a new SBDefinition
Stores the SBDefinition in the underlying data store, with an identifier generated from SKUID
- Status Codes:
200 OK – OK, the SBDefinition was created
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- GET /sbds/{sbd_id}
Get SBDefinition by identifier
Retrieves the SBDefinition with the given identifier from the underlying data store, if available
- Parameters:
sbd_id (string) –
- Status Codes:
200 OK – OK
404 Not Found – Not Found
500 Internal Server Error – Internal Server Error
- PUT /sbds/{sbd_id}
Updates an SBDefinition by identifier
Updates the SBDefinition with the given identifier in the underlying data store, creating a new version. If the identifier does not exist in the data store, a not found error will be returned.
- Parameters:
sbd_id (string) –
- Status Codes:
200 OK – OK, the SBDefinition was created or updated
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- GET /sbis
Get SBInstance filter by the query parameter
Retrieves the SBInstances which match the query parameters. Currently only a single query field is permitted, eg user, entity_id 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. Added pattern search support on scheduling block instance IDs.
- Query Parameters:
user (string) –
match_type (string) –
created_before (string) –
created_after (string) –
last_modified_before (string) –
last_modified_after (string) –
entity_id (string) –
- Status Codes:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
500 Internal Server Error – Internal Server Error
- POST /sbis
Create a new SBInstance
Stores the SBInstance in the underlying data store, with an identifier generated from SKUID
- Status Codes:
200 OK – OK, the SBInstance was created
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- 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:
200 OK – OK
404 Not Found – Not Found
500 Internal Server Error – Internal Server Error
- PUT /sbis/{sbi_id}
Updates an SBInstance by identifier
Updates the SBDInstance with the given identifier in the underlying data store, mutating the existing first version. If the identifier does not exist in the data store, a not found error will be returned.
- Parameters:
sbi_id (string) –
- Status Codes:
200 OK – OK, the SBInstance was created or updated
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- GET /ebs
Get ExecutionBlock filter by the query parameter
Retrieves the ExecutionBlocks which match the query parameters. Currently only a single query field is permitted, eg user, entity_id 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. Added pattern search support on Execution block IDs.
- Query Parameters:
user (string) –
match_type (string) –
created_before (string) –
created_after (string) –
last_modified_before (string) –
last_modified_after (string) –
entity_id (string) –
- Status Codes:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
500 Internal Server Error – Internal Server Error
- POST /ebs
Create a new ExecutionBlock
Stores the ExecutionBlock in the underlying data store, with an identifier generated from SKUID
- Status Codes:
200 OK – OK, the ExecutionBlock was created
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- 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:
200 OK – OK
404 Not Found – Not Found
500 Internal Server Error – Internal Server Error
- PUT /ebs/{eb_id}
Updates an ExecutionBlock by identifier
Updates the ExecutionBlock with the given identifier in the underlying data store, mutating the existing first version. If the identifier does not exist in the data store, a not found error will be returned.
- Parameters:
eb_id (string) –
- Status Codes:
200 OK – OK, the ExecutionBlock was created or updated
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- 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:
200 OK – The record was successfully added to the ExecutionBlock
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
500 Internal Server Error – Internal Server Error
- GET /prjs
Get Project filter by the query parameter
Retrieves the Projects which match the query parameters. Currently only a single query field is permitted, eg user, entity_id 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. added pattern search on project IDs.
- Query Parameters:
user (string) –
match_type (string) –
created_before (string) –
created_after (string) –
last_modified_before (string) –
last_modified_after (string) –
entity_id (string) –
- Status Codes:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
500 Internal Server Error – Internal Server Error
- POST /prjs
Create a new Project
Stores the Project in the underlying data store, with an identifier generated from SKUID
- Status Codes:
200 OK – OK, the Project was created
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- 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:
200 OK – OK
404 Not Found – Not Found
500 Internal Server Error – Internal Server Error
- PUT /prjs/{prj_id}
Updates an Project by identifier
Updates the Project with the given identifier in the underlying data store, creating a new version. If the identifier does not exist in the data store, a not found error will be returned.
- Parameters:
prj_id (string) –
- Status Codes:
200 OK – OK, the ExecutionBlock was created or updated
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- GET /prsls/{prsl_id}
Get Proposal by identifier
Retrieves the Proposal with the given identifier from the underlying data store, if available
- Parameters:
prsl_id (string) – Unique identifier for the proposal. Values should be alphanumeric and in SKUID format for Proposal IDs.
- Status Codes:
200 OK – OK
404 Not Found – Not Found
500 Internal Server Error – Internal Server Error
- PUT /prsls/{prsl_id}
Updates an Proposal by identifier
Updates the Proposal with the given identifier in the underlying data store, creating a new version. If the identifier does not exist in the data store, a not found error will be returned.
- Parameters:
prsl_id (string) – Unique identifier for the proposal. Values should be alphanumeric and in SKUID format for Proposal IDs.
- Status Codes:
200 OK – OK, the ExecutionBlock was created or updated
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error
- GET /prsls
Get Proposal filter by the query parameter
Retrieves the Proposal which match the query parameters. Currently only a single query field is permitted, eg user, entity_id 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. added pattern search on propsal IDs.
- Query Parameters:
user (string) –
match_type (string) –
created_before (string) –
created_after (string) –
last_modified_before (string) –
last_modified_after (string) –
entity_id (string) –
- Status Codes:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
500 Internal Server Error – Internal Server Error
- POST /prsls
Create a new Proposal
Stores the Proposal in the underlying data store, with an identifier generated from SKUID
- Status Codes:
200 OK – OK, the Proposal was created
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
404 Not Found – Not Found
422 Unprocessable Entity – Unprocessable Entity, semantic error in request eg mismatched IDs
500 Internal Server Error – Internal Server Error