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.
The is also a root end point which will support PUT for multiple resources as an atomic operation.
The endpoints, with the accepted requests and expected responses are documented below:
- GET /
Returns a home page for the ODA API
Returns a basic HTML page for the ODA API with links to documents
- Status Codes:
200 OK – OK
- 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 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:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
500 Internal Server Error – Internal Server Error
- 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:
200 OK – OK
404 Not Found – Not Found
500 Internal Server Error – Internal Server Error
- 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:
200 OK – OK, the SBDefinition was created or updated
400 Bad Request – Bad Request, eg 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 /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:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
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}
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:
200 OK – OK, the SBInstance was created or updated
400 Bad Request – Bad Request, eg 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 /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:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
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}
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:
200 OK – OK, the ExecutionBlock was created or updated
400 Bad Request – Bad Request, eg 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
- POST /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 sucessfully 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
- POST /ebs/create
Create an ExecutionBlock with a generated eb_id
Creates an ‘empty’ ExecutionBlock, ie one without any commands and responses, with an eb_id generated from SKUID and persists it in the ODA.
- Status Codes:
200 OK – OK
500 Internal Server Error – Internal Server Error
- 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:
200 OK – OK
400 Bad Request – Bad Request, eg validation of against OpenAPI spec failed
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}
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:
200 OK – OK, the ExecutionBlock was created or updated
400 Bad Request – Bad Request, eg 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