API Package

This document contains all the documentation for the package topchef.api. The purpose of this package is to implement all the HTTP endpoints, and map all the HTTP requests to the business logic needed to fulfill them.

Abstract Endpoints

Abstract Endpoint

Provides an abstract endpoint unique to this API from which all other endpoints will inherit. This takes care of managing the database session, as well as providing a links object containing the endpoint to itself.

class topchef.api.abstract_endpoints.abstract_endpoint.AbstractEndpoint(session: sqlalchemy.orm.session.Session, request: flask.wrappers.Request = <LocalProxy unbound>) → None[source]

Defines the abstract endpoint, taking care of errors.

Error reporting becomes a little more complicated when dealing with HTTP APIs, as the separation between errors and errors becomes more pronounced. For instance, when de-serializing invalid user input, the error that results from validation must be reported, but the program is still in a well-determined state that precludes the need for throwing an exception.

Error reporting in this API relies heavily on APIException. Errors can be reported either destructively by raising the APIException, or non-destructively by appending the exception to the errors object. In order to stop execution of the endpoint and return an error response, raise AbstractEndpoint.Abort.

The links object exists primarily to display a link to the current endpoint. If an endpoint will be paginated, the pagination links should go into this object.

exception Abort[source]

Exception thrown if the endpoint has to stop. The error response will be returned at this point.

AbstractEndpoint.__init__(session: sqlalchemy.orm.session.Session, request: flask.wrappers.Request = <LocalProxy unbound>) → None[source]
Parameters:
  • session – The database session to be used for interacting with the database.
  • request – The Flask request object to use for running the request
AbstractEndpoint._close_session(session: sqlalchemy.orm.session.Session) → None[source]

Safely close the session. If there is an error from SQLAlchemy, add it to the other errors

Parameters:session – The session to close
static AbstractEndpoint._error_code_reducer(first_code: int, second_code: int) → int[source]
Parameters:
  • first_code – The “left side” of the status code to compare
  • second_code – The “right side” of the status codes
Returns:

The status code that should be returned
AbstractEndpoint._error_response
Returns:A response containing the errors that were encountered while working with the API
AbstractEndpoint._error_status_code
Returns:The status code that should be thrown for an error response. The status code to be returned is the most general one for the errors provided. If all the errors have the same status code, then the status code to return is the status code for the errors. If all the errors are 400-series status codes, then the error code that will be returned is 400. If there is a mixture of 400 and 500 series error codes, then the error code to return will be 500
AbstractEndpoint._get_method_for_request_method(request_method: str) → typing.Callable[[typing.Any], flask.wrappers.Response][source]
Parameters:request_method – The HTTP request method requested by Flask
Returns:The method to run
AbstractEndpoint._get_method_not_allowed_response(method: str, allowed_methods: typing.Iterable[str]) → flask.wrappers.Response[source]
Parameters:
  • method – The method that caused the exception to be thrown
  • allowed_methods – The allowed methods on the API
Returns:

A Flask response indicating why the error was thrown
AbstractEndpoint._serialized_errors
Returns:The errors encountered in the API after having been serialized
AbstractEndpoint.database_session
Returns:The SQLAlchemy session used to contact the database
AbstractEndpoint.dispatch_request(*args, **kwargs) → flask.wrappers.Response[source]

Create a session, and dispatch the request to the appropriate methods

Parameters:
  • args – The function arguments built by Flask that are to be sent to the method called up by this dispatch
  • kwargs – The keyword arguments built by Flask, that are going to be sent to the method dispatched here
AbstractEndpoint.errors
Returns:The errors encountered in the API
Returns:The relevant links required for the endpoint
AbstractEndpoint.request_json
Returns:The JSON in the request body, if it exists

Endpoint for Service

Takes a more meta approach to wrapping services by providing a metaclass to use for wrapping the service endpoint

class topchef.api.abstract_endpoints.endpoint_for_service.AbstractEndpointForServiceMeta(name, bases, namespace) → None[source]

Metaclass for endpoints requiring decoration that are also abstract classes. This class exists primarily to avoid metaclass conflicts

class topchef.api.abstract_endpoints.endpoint_for_service.EndpointForServiceIdMeta(name, bases, namespace) → None[source]

A metaclass for getting the service

_service_decorator(function_to_decorate)[source]
Parameters:function_to_decorate – The service endpoint to decorate
Returns:

API Metadata

Describes the root endpoint of the API, which provides some metadata about the API.

class topchef.api.api_metadata.APIMetadata(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, metadata: topchef.models.interfaces.api_metadata.APIMetadata = <topchef.models.api_metadata.APIMetadata object>) → None[source]

Maps HTTP GET methods to the API’s root endpoint

__init__(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, metadata: topchef.models.interfaces.api_metadata.APIMetadata = <topchef.models.api_metadata.APIMetadata object>) → None[source]
Parameters:
  • session – The SQLAlchemy ORM Session to use for communicating with the database. This is required by AbstractEndpoint in order to perform its transaction management
  • flask_request – The request to process. By default, this is flask’s request variable
  • metadata – The metadata to serialize. By default, this is an instance of the MetadataModel that pulls all of its values from the config script.
get() → flask.wrappers.Response[source]

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"
        }
    }
}
Statuscode 200:The request completed successfully
Returns:A response containing the metadata

Service List

Describes the endpoint for listing services

class topchef.api.services_list.ServicesList(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None) → None[source]

Maps methods for listing services as well as creating a service

__init__(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None) → None[source]

Create a service list model that is capable of getting services from the DB

Parameters:session – The database session to use
_data
Returns:The JSON corresponding to all the services loaded onto the API
_meta
Returns:The endpoint metadata
get() → flask.wrappers.Response[source]

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"
        }
    }
}
Statuscode 200:The request completed successfully
Returns:A Flask response with the appropriate data
post() → flask.wrappers.Response[source]

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 the title and description fields 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 required keyword 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"
    }
}
Statuscode 201:The service was successfully created
Statuscode 400:The request could not be understood, due to either incorrect JSON, or not adhering to the schema in the new_service_schema presented in the GET method of this endpoint
Returns:A flask response indicating whether creation of the service was successful or not

Service Details

Describes an endpoint where detailed information about the service can be obtained

class topchef.api.service_detail.ServiceDetail(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None) → None[source]

Describes the endpoint that returns the details for a particular service

get(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response[source]

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"
            }
        }
    }
Statuscode 200:The request completed successfully
Statuscode 404:A service with the ID was not found
Parameters:service – The service for which a response is to be retrieved
Returns:A flask response with the appropriate data
patch(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response[source]

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
}
Statuscode 200:The request completed successfully
Statuscode 400:If an attempt is made to provide JSON as a request body, and the JSON is either syntactically or semantically incorrect.
Statuscode 404:A service with that ID was not found in the database
Parameters:service – The service to patch
Returns:Reset the service’s timeout
class topchef.api.service_detail.ServiceDetailForServiceID(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None) → None[source]

Contains a mixin to help the web endpoints parse service_id string as they come raw from the HTTP endpoint

get(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response

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"
            }
        }
    }
Statuscode 200:The request completed successfully
Statuscode 404:A service with the ID was not found
Parameters:service – The service for which a response is to be retrieved
Returns:A flask response with the appropriate data
patch(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response

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
}
Statuscode 200:The request completed successfully
Statuscode 400:If an attempt is made to provide JSON as a request body, and the JSON is either syntactically or semantically incorrect.
Statuscode 404:A service with that ID was not found in the database
Parameters:service – The service to patch
Returns:Reset the service’s timeout

Service Queue

Maps the /services/<service_id>/queue endpoint

class topchef.api.job_queue.JobQueueForService(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None) → None[source]

Maps the endpoint

static _is_job_registered(job: topchef.models.interfaces.job.Job)[source]
Parameters:job – The job to check if it is registered
Returns:
get(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response[source]

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
Statuscode 200:The request completed successfully
Statuscode 204:The request completed successfully, but there are no jobs in the queue right now.
Statuscode 404:A service with that ID could not be found
Parameters:service – The service for which the next few jobs are to be retrieved
Returns:A flask response with the appropriate data
class topchef.api.job_queue.JobQueueForServiceID(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None) → None[source]

Modifies the web methods in order to accept and resolve services for a given service UUID

get(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response

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
Statuscode 200:The request completed successfully
Statuscode 204:The request completed successfully, but there are no jobs in the queue right now.
Statuscode 404:A service with that ID could not be found
Parameters:service – The service for which the next few jobs are to be retrieved
Returns:A flask response with the appropriate data

Jobs For Service

Maps the /services/<service_id>/jobs endpoint

class topchef.api.jobs_for_service.JobsForServiceEndpoint(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None, validator_factory: typing.Union[type, NoneType] = None)[source]

Describes the endpoint. A GET request to this endpoint returns all the jobs registered for a particular service. A POST request to this endpoint will allow the user to create new jobs for the service. A PATCH request here will reset the time since the service was last polled

get(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response[source]

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"
        }
    }
}
Statuscode 200:The request completed successfully
Statuscode 404:A service with that ID could not be found
Parameters:service – The service for which jobs are to be retrieved
Returns:A flask response containing the data to display to the user
post(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response[source]

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 a Location header 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"
}
Statuscode 201:The job was successfully created
Statuscode 400:The job could not be created.
Statuscode 404:A service with the ID could not be found
Parameters:service – The service for which the new job is to be made
Returns:A flask response with the appropriate response as per the documentation in this endpoint
class topchef.api.jobs_for_service.JobsForServiceID(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, service_list: typing.Union[topchef.models.interfaces.service_list.ServiceList, NoneType] = None, validator_factory: typing.Union[type, NoneType] = None)[source]

Endpoint that maps the web endpoints defined in the superclass to match service ids

get(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response

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"
        }
    }
}
Statuscode 200:The request completed successfully
Statuscode 404:A service with that ID could not be found
Parameters:service – The service for which jobs are to be retrieved
Returns:A flask response containing the data to display to the user
post(service: topchef.models.interfaces.service.Service) → flask.wrappers.Response

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 a Location header 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"
}
Statuscode 201:The job was successfully created
Statuscode 400:The job could not be created.
Statuscode 404:A service with the ID could not be found
Parameters:service – The service for which the new job is to be made
Returns:A flask response with the appropriate response as per the documentation in this endpoint

Job List

Describes an API endpoint that describes the endpoint for /jobs

class topchef.api.jobs_list.JobsList(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, job_list_model: typing.Union[topchef.models.interfaces.job_list.JobList, NoneType] = None) → None[source]

Maps HTTP requests for the /jobs endpoint to methods in this class

__init__(session: sqlalchemy.orm.session.Session, flask_request: flask.wrappers.Request = <LocalProxy unbound>, job_list_model: typing.Union[topchef.models.interfaces.job_list.JobList, NoneType] = None) → None[source]
Parameters:
  • session – The session to use
  • flask_request – The Flask request that this endpoint needs to process
_data
Returns:The JSON containing a list of all the jobs on the system
_data_schema
Returns:A JSON schema for the data in the data key of this response
get() → flask.wrappers.Response[source]

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"
        }
    }
}
Statuscode 200:The request completed successfully
Returns:The list of all jobs on the system