HTTP API Documentation¶
This section contains the reference documentation for TopChef’s HTTP API. It describes the API endpoints, what each method does at each endpoint, and the reasons why a given HTTP status code will be returned for a given request. Example requests and responses are also provided.
-
GET/validator¶ Return a schema indicating how the endpoint is to be used. The
validator_schemakeyword contains a JSON schema that must be satisified in order toPOSTrequests to the APIExample Response
HTTP/1.1 200 OK Content-Type: application/json { "data": {}, "links": { "self": "http://localhost:5000/validator" }, "meta": { "validator_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The POST request schema", "properties": { "object": { "title": "object", "type": "object" }, "schema": { "title": "schema", "type": "object" } }, "required": [ "object", "schema" ], "title": "JSON Schema Validator", "type": "object" } } }
Status Codes: - 200 OK – The request completed successfully
Return: A flask response indicating how this validator is to be used
-
POST/validator¶ If a JSON schema validator cannot be found for the client side, use this method to validate against the server side
Example Request
POST /validator HTTP/1.1 Content-Type: application/json { "schema": { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Validator Schema", "description": "A schema used for documenting this endpoint", "type": "object", "properties": { "value": { "type": "integer", "minimum": 1, "maximum": 10 } } }, "object": { "value": 1 } }
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "data": { "status": "Validation was successful" }, "links": { "self": "http://localhost:5000/validator" } }
Status Codes: - 200 OK – The Validation completed successfully. The provided JSON object is an instance of the provided JSON Schema
- 400 Bad Request – The validation was not successful. This may be due
to the request not being correct JSON, or to the object not
matching the schema. The
errorsobject returned in this response will contain more information related to the error
Return: A flask response indicating whether validation was successful or not
-
GET/services¶ Returns a list of all services exposed by this API
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "data": [ { "description": "A quick testing service", "id": "495d76fd-044c-4f02-8815-5ec6e7634330", "name": "Testing Service" }, ], "links": { "self": "http://localhost:5000/services" }, "meta": { "new_service_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "properties": { "description": { "title": "description", "type": "string" }, "job_registration_schema": { "title": "job_registration_schema", "type": "object" }, "job_result_schema": { "title": "job_result_schema", "type": "object" }, "name": { "title": "name", "type": "string" } }, "required": [ "description", "job_registration_schema", "job_result_schema", "name" ], "title": "New Service Schema", "type": "object" }, "service_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "properties": { "description": { "readonly": true, "title": "description", "type": "string" }, "id": { "format": "uuid", "readonly": true, "title": "id", "type": "string" }, "name": { "readonly": true, "title": "name", "type": "string" } }, "required": [ "description", "id", "name" ], "title": "Service overview schema", "type": "object" } } }
Status Codes: - 200 OK – The request completed successfully
Return: A Flask response with the appropriate data
-
POST/services¶ Create a new service
Example Request
The request below will create a service for running Rabi experiments remotely. The only experiment parameter in this case is the
pulse_time. In the case of the Rabi experiment, this can represent how long the pulse is to be switched on for. Using JSON schema, we can also bound the pulse time to be between 0 and 50 microseconds. This is done because we know ahead of time that it would be silly to run Rabi experiments with a negative pulse time. All thetitleanddescriptionfields in the schema are optional, and are there so that humans understand the schema.Warning
By default, properties in JSON schema are not required. There needs to be a
requiredkeyword with the required parameters in the schema in order to mandate that objects have the property.POST /services HTTP/1.1 Host: example.com Content-Type: application/json { "name": "NV Experiments", "description": "Describes a sample NV center experiment", "job_registration_schema": { "type": "object", "$schema": "http://json-schema.org/draft-04/schema#", "title": "Job Registration Schema", "description": "Describes a schema for a Rabi experiment only", "properties": { "pulse_time": { "type": "integer", "minimum": 0, "maximum": 50e-6 } }, "required": [ "pulse_time" ] }, "job_result_schema": { "type": "object", "$schema": "http://json-schema.org/draft-04/schema#", "title": "Job Result Schema", "description": "Describes a schema for the results", "properties": { "light_count": { "type": "integer", "minimum": 0 }, "dark_count": { "type": "integer", "minimum": 0 }, "result_count": { "type": "integer", "minimum": 0 } }, "required": [ "light_count", "dark_count", "result_count" ] } }
Example Response
HTTP/1.1 201 CREATED Content-Type: application/json { "data": { "message": "service successfully created" }, "links": { "self": "http://localhost:5000/services" } }
Status Codes: - 201 Created – The service was successfully created
- 400 Bad Request – The request could not be understood, due to either
incorrect JSON, or not adhering to the schema in the
new_service_schemapresented in theGETmethod of this endpoint
Return: A flask response indicating whether creation of the service was successful or not
-
GET/jobs¶ Get the list of all jobs on the system
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "data": [ { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "status": "REGISTERED" } ], "links": { "self": "http://127.0.0.1:5000/jobs" }, "meta": { "data_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "Describes how jobs are presented in the \"data\" endpoint", "items": { "$schema": "http://json-schema.org/draft-04/schema#", "properties": { "date_submitted": { "format": "date-time", "readonly": true, "title": "date_submitted", "type": "string" }, "id": { "format": "uuid", "readonly": true, "title": "id", "type": "string" }, "status": { "enum": [ "REGISTERED", "WORKING", "COMPLETED", "ERROR" ], "type": "string" } }, "required": [ "date_submitted", "id", "status" ], "type": "object" }, "title": "Job Endpoint Schema", "type": "array" } } }
Status Codes: - 200 OK – The request completed successfully
Return: The list of all jobs on the system
-
GET/¶ Get the metadata for this API
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "data": { "documentation_url": "https://topchef.readthedocs.io/en/latest/", "maintainer_email": "michalkononenko@gmail.com", "maintainer_name": "Michal Kononenko", "source_code_repository_url": "https://www.github.com/MichalKononenko/TopChef", "version": "0.1dev" }, "links": { "self": "http://localhost:5000/" }, "meta": { "schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "Describes the JSON schema for describing API metadata", "properties": { "documentation_url": { "title": "documentation_url", "type": "string" }, "maintainer_email": { "title": "maintainer_email", "type": "string" }, "maintainer_name": { "title": "maintainer_name", "type": "string" }, "source_code_repository_url": { "title": "source_code_repository_url", "type": "string" }, "version": { "title": "version", "type": "string" } }, "required": [ "documentation_url", "maintainer_email", "maintainer_name", "source_code_repository_url", "version" ], "title": "API Metadata", "type": "object" } } }
Status Codes: - 200 OK – The request completed successfully
Return: A response containing the metadata
-
GET/services/(service_id)/jobs/next¶ Example Response With Job
HTTP/1.1 200 OK Content-Type: application/json { "data": { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "parameters": { "foo": "bar" }, "results": { "foo": "bar" }, "status": "REGISTERED" }, "links": { "self": "http://localhost:5000/services/495d76fd-044c-4f02-8815-5ec6e7634330/jobs/next" }, "meta": { "job_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The schema representing the job", "properties": { "date_submitted": { "format": "date-time", "title": "date_submitted", "type": "string" }, "id": { "format": "uuid", "title": "id", "type": "string" }, "parameters": { "title": "parameters", "type": "object" }, "results": { "title": "results", "type": "object" }, "status": { "enum": [ "REGISTERED", "WORKING", "COMPLETED", "ERROR" ], "type": "string" } }, "required": [ "id", "parameters", "results", "status" ], "title": "Job Schema", "type": "object" } } }
Status Codes: - 200 OK – The request completed successfully. The next job is available in the request body
- 204 No Content – The request completed successfully, but no next job is available
- 404 Not Found – A service with that ID could not be found
Parameters: - service – The service for which the next job is to be obtained
Return: A flask response with the appropriate data
-
GET/services/(service_id)/queue¶ Returns the next 10 jobs available for a given service
Example Request
GET /services/495d76fd-044c-4f02-8815-5ec6e7634330/queue HTTP/1.1 Content-Type: application/json
Example Response With A Job
HTTP/1.1 200 OK Content-Type: application/json { "data": [ { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "parameters": { "foo": "bar" }, "results": null, "status": "REGISTERED" } ], "links": { "self": "http://localhost:5000/services/495d76fd-044c-4f02-8815-5ec6e7634330/queue" }, "meta": { "data_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The schema for the data in the \"data\" key", "items": { "$schema": "http://json-schema.org/draft-04/schema#", "properties": { "date_submitted": { "format": "date-time", "title": "date_submitted", "type": "string" }, "id": { "format": "uuid", "title": "id", "type": "string" }, "parameters": { "title": "parameters", "type": "object" }, "results": { "title": "results", "type": "object" }, "status": { "enum": [ "REGISTERED", "WORKING", "COMPLETED", "ERROR" ], "type": "string" } }, "required": [ "id", "parameters", "results", "status" ], "type": "object" }, "title": "Job List Schema", "type": "array" } } }
Example Response With No Job
HTTP/1.1 204 NO CONTENT
Status Codes: - 200 OK – The request completed successfully
- 204 No Content – The request completed successfully, but there are no jobs in the queue right now.
- 404 Not Found – A service with that ID could not be found
Parameters: - service – The service for which the next few jobs are to be retrieved
Return: A flask response with the appropriate data
-
GET/services/(service_id)/jobs¶ Get the list of jobs available for a service
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "data": [ { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "parameters": { "foo": "bar" }, "results": { "foo": "bar" }, "status": "REGISTERED" } ], "links": { "self": "http://localhost:5000/services/495d76fd-044c-4f02-8815-5ec6e7634330/jobs" }, "meta": { "data_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The schema for reading data contained in the data key of this response", "items": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The schema for reading data contained in the data key of this response", "properties": { "date_submitted": { "format": "date-time", "title": "date_submitted", "type": "string" }, "id": { "format": "uuid", "title": "id", "type": "string" }, "parameters": { "title": "parameters", "type": "object" }, "results": { "title": "results", "type": "object" }, "status": { "enum": [ "REGISTERED", "WORKING", "COMPLETED", "ERROR" ], "type": "string" } }, "required": [ "id", "parameters", "results", "status" ], "title": "Data Schema", "type": "object" }, "title": "Data Schema", "type": "array" }, "new_job_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The schema that a POST request must satisfy in order to create a new job", "properties": { "parameters": { "type": "object" } }, "title": "New Job Schema", "type": "object" } } }
Status Codes: - 200 OK – The request completed successfully
- 404 Not Found – A service with that ID could not be found
Parameters: - service – The service for which jobs are to be retrieved
Return: A flask response containing the data to display to the user
-
POST/services/(service_id)/jobs¶ Create a new job. The request must satisfy the schema specified in the key
meta/new_job_schema. A request indicating a successful response will also include aLocationheader indicating where the new job is located.Example Request
POST /services/668ac2ea-063d-4122-ba7a-97a3e8e46a8a/jobs HTTP/1.1 Content-Type: application/json { "parameters": { "experiment_type": "RABI", "wait_time": 500e-9 } }
Example Response
HTTP/1.1 201 CREATED Content-Type: application/json Location: http://localhost:5000/jobs/42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7 { "data": { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "parameters": { "experiment_type": "RABI", "wait_time": 500e-9, }, "results": null, "status": "REGISTERED" } "meta": "new job ID is b0b58425-165f-4add-97b0-86da6b38757f" }
Status Codes: - 201 Created – The job was successfully created
- 400 Bad Request – The job could not be created.
- 404 Not Found – A service with the ID could not be found
Parameters: - service – The service for which the new job is to be made
Return: A flask response with the appropriate response as per the documentation in this endpoint
-
GET/services/(service_id)¶ Return details for a given service
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "data": { "description": "A quick testing service", "has_timed_out": true, "id": "495d76fd-044c-4f02-8815-5ec6e7634330", "is_service_available": false, "job_registration_schema": { "type": "object" }, "job_result_schema": { "type": "object" }, "jobs": [ { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "status": "REGISTERED" } ], "name": "Testing Service", "timeout": 30 }, "links": { "self": "/services/495d76fd-044c-4f02-8815-5ec6e7634330" }, "meta": { "service_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "A comprehensive schema for services", "properties": { "description": { "readonly": true, "title": "description", "type": "string" }, "has_timed_out": { "readonly": true, "title": "has_timed_out", "type": "boolean" }, "id": { "format": "uuid", "readonly": true, "title": "id", "type": "string" }, "is_service_available": { "readonly": true, "title": "is_service_available", "type": "boolean" }, "job_registration_schema": { "readonly": true, "title": "job_registration_schema", "type": "object" }, "job_result_schema": { "readonly": true, "title": "job_result_schema", "type": "object" }, "jobs": { "items": { "type": "object" }, "type": "array" }, "name": { "readonly": true, "title": "name", "type": "string" }, "timeout": { "readonly": true, "title": "timeout", "type": "string" } }, "required": [ "description", "has_timed_out", "id", "is_service_available", "job_registration_schema", "job_result_schema", "name", "timeout" ], "title": "Detailed Service Schema", "type": "object" } } }
Status Codes: - 200 OK – The request completed successfully
- 404 Not Found – A service with the ID was not found
Parameters: - service – The service for which a response is to be retrieved
Return: A flask response with the appropriate data
-
PATCH/services/(service_id)¶ Change the mutable parameters of the service
Example Request
PATCH /services/<service_id> HTTP/1.1 Content-Type: application/json { "is_available": false, "name": "Changed name", "description": "Changed description", "timeout": 20 }
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "description": "A quick testing service", "has_timed_out": true, "id": "495d76fd-044c-4f02-8815-5ec6e7634330", "is_service_available": false, "job_registration_schema": { "type": "object" }, "job_result_schema": { "type": "object" }, "jobs": [ { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "status": "REGISTERED" } ], "name": "Testing Service", "timeout": 30 }
Status Codes: - 200 OK – The request completed successfully
- 400 Bad Request – If an attempt is made to provide JSON as a request body, and the JSON is either syntactically or semantically incorrect.
- 404 Not Found – A service with that ID was not found in the database
Parameters: - service – The service to patch
Return: Reset the service’s timeout
-
GET/jobs/(job_id)¶ Return the details for a job with a particular ID
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "data": { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "parameters": { "foo": "bar" }, "results": null, "status": "REGISTERED" }, "links": { "self": "http://localhost:5000/jobs/42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7" }, "meta": { "job_info_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The schema for all displayable data for a job", "properties": { "date_submitted": { "format": "date-time", "title": "date_submitted", "type": "string" }, "id": { "format": "uuid", "title": "id", "type": "string" }, "parameters": { "title": "parameters", "type": "object" }, "results": { "title": "results", "type": "object" }, "status": { "enum": [ "REGISTERED", "WORKING", "COMPLETED", "ERROR" ], "type": "string" } }, "required": [ "id", "parameters", "results", "status" ], "title": "Detailed Job Schema", "type": "object" }, "patch_request_schema": { "$schema": "http://json-schema.org/draft-04/schema#", "description": "The schema for all displayable data for a job", "properties": { "results": { "title": "results", "type": "object" }, "status": { "enum": [ "REGISTERED", "WORKING", "COMPLETED", "ERROR" ], "type": "string" } }, "required": [], "title": "Detailed Job Schema", "type": "object" } } }
Status Codes: - 200 OK – The request completed successfully
- 404 Not Found – A job with that ID could not be found
Parameters: - job – The job for which a response is to be obtained
Return: A Flask response containing the data for a given job
-
PATCH/jobs/(job_id)¶ Modify the mutable properties of the job. These are the job status and the job results. A request to this endpoint must satisfy the schema in the
patch_request_schemakey in themetakey of the GET request of this endpointExample Request
Let’s say we completed the NV-experiment, and received a light count of 153 photons, a dark count of 100 photons, and a result count of 113 photons. This request will set the job status to “COMPLETED” to indicate that the job is finished, and it will update the job results. Keep in mind that we need to satisfy the
job_result_schemaof the job’s service in order to post valid results. Our results will be validated here.PATCH /jobs/42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7 HTTP/1.1 Content-Type: application/json { "status": "COMPLETED", "results": { "light_count": 153, "dark_count": 100, "result_count": 113 } }
Example Response
HTTP/1.1 200 OK Content-Type: application/json { "date_submitted": "2017-08-15T18:29:07.902093+00:00", "id": "42094fe4-9c71-4d6e-94fd-7ed6e2b46ce7", "parameters": { "pulse_time": 250e-9 }, "results": { "light_count": 153, "dark_count": 100, "result_count": 113 }, "status": "COMPLETED" }
Status Codes: - 200 OK – The request completed successfully
- 404 Not Found – A job with that ID could not be found
Parameters: - job – The job to be modified
Return: The response