REST API

The items in this list document the REST API calls which can be made against the server, this includes both the Body and the Responses for the various GET, POST, and PUT calls.

The entries are organized such that the API is presented first, separated by objects. The last group of entries are common models which are parts of the API Bodies and Responses (like Metadata), but occur many times in the normal calls.

KV Store

class qcportal.models.rest_models.KVStoreGETBody[source]
Parameters
  • meta (EmptyMeta, Default: {}) – There is no metadata accepted, so an empty metadata is sent for completion.

  • data (Data) – Data of the KV Get field: consists of a dict for Id of the Key/Value object to fetch.

class qcportal.models.rest_models.KVStoreGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (Dict[str, Any]) – The entries of Key/Value object requested.

Molecule

class qcportal.models.rest_models.MoleculeGETBody[source]
Parameters
  • meta (QueryMeta, Optional) – Standard Fractal Server metadata for Database queries containing pagination information

  • data (Data) – Data fields for a Molecule query.

class qcportal.models.rest_models.MoleculeGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (Molecule) – The List of Molecule objects found by the query.

class qcportal.models.rest_models.MoleculePOSTBody[source]
Parameters
  • meta (EmptyMeta, Default: {}) – There is no metadata accepted, so an empty metadata is sent for completion.

  • data (Molecule) – A list of Molecule objects to add to the Database.

class qcportal.models.rest_models.MoleculePOSTResponse[source]
Parameters
  • meta (ResponsePOSTMeta) – Standard Fractal Server response metadata for POST/add type requests.

  • data (List[ObjectId]) – A list of Id’s assigned to the Molecule objects passed in which serves as a unique identifier in the database. If the Molecule was already in the database, then the Id returned is its existing Id (entries are not duplicated).

Keywords

class qcportal.models.rest_models.KeywordGETBody[source]
Parameters
  • meta (QueryMeta, Optional) – Standard Fractal Server metadata for Database queries containing pagination information

  • data (Data) – The formal query for a Keyword fetch, contains id or hash_index for the object to fetch.

class qcportal.models.rest_models.KeywordGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (KeywordSet) – The KeywordSet found from in the database based on the query.

class qcportal.models.rest_models.KeywordPOSTBody[source]
Parameters
  • meta (EmptyMeta, Default: {}) – There is no metadata with this, so an empty metadata is sent for completion.

  • data (KeywordSet) – The list of KeywordSet objects to add to the database.

class qcportal.models.rest_models.KeywordPOSTResponse[source]
Parameters
  • data (List[ObjectId]) – The Ids assigned to the added KeywordSet objects. In the event of duplicates, the Id will be the one already found in the database.

  • meta (ResponsePOSTMeta) – Standard Fractal Server response metadata for POST/add type requests.

Collections

class qcportal.models.rest_models.CollectionGETBody[source]
Parameters
  • meta (QueryFilter, Optional) – Additional metadata to make with the query. Collections can only have an include/exclude key in its meta and therefore does not follow the standard GET metadata model.

  • data (Data) – Information about the Collection to search the database with.

class qcportal.models.rest_models.CollectionGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (List[Dict[str, Union[Any, NoneType]]]) – The Collection objects returned by the server based on the query.

class qcportal.models.rest_models.CollectionPOSTBody[source]
Parameters
  • meta (Meta, Optional) – Metadata to specify how the Database should handle adding this Collection if it already exists. Metadata model for adding Collections can only accept overwrite as a key to choose to update existing Collections or not.

  • data (Data) – The data associated with this Collection to add to the database.

class qcportal.models.rest_models.CollectionPOSTResponse[source]
Parameters
  • data (str, Optional) – The Id of the Collection uniquely pointing to it in the Database. If the Collection was not added (e.g. overwrite=False for existing Collection), then a None is returned.

  • meta (ResponsePOSTMeta) – Standard Fractal Server response metadata for POST/add type requests.

Result

class qcportal.models.rest_models.ResultGETBody[source]
Parameters
  • meta (QueryMetaFilter, Optional) – Fractal Server metadata for Database queries allowing for filtering and pagination

  • data (Data) – The keys with data to search the database on for individual quantum chemistry computations.

class qcportal.models.rest_models.ResultGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (Union[ResultRecord, List[Dict[str, Any]]]) – Results found from the query. This is a list of ResultRecord in most cases, however, if a projection was specified in the GET request, then a dict is returned with mappings based on the projection.

Procedures

class qcportal.models.rest_models.ProcedureGETBody[source]
Parameters
  • meta (QueryMetaFilter, Optional) – Fractal Server metadata for Database queries allowing for filtering and pagination

  • data (Data) – The keys with data to search the database on for Procedures.

class qcportal.models.rest_models.ProcedureGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (List[Dict[str, Union[Any, NoneType]]]) – The list of Procedure specs found based on the query.

Task Queue

class qcportal.models.rest_models.TaskQueueGETBody[source]
Parameters
  • meta (QueryMetaFilter, Optional) – Fractal Server metadata for Database queries allowing for filtering and pagination

  • data (Data) – The keys with data to search the database on for Tasks.

class qcportal.models.rest_models.TaskQueueGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (Union[TaskRecord, List[Dict[str, Any]]]) – Tasks found from the query. This is a list of TaskRecord in most cases, however, if a projection was specified in the GET request, then a dict is returned with mappings based on the projection.

class qcportal.models.rest_models.TaskQueuePOSTBody[source]
Parameters
  • meta (Meta) – The additional specification information for the Task to add to the Database.

  • data (List[Union[ObjectId, Molecule]]) – The list of either Molecule objects or Molecule Id’s (those already in the database) to submit as part of this Task.

class qcportal.models.rest_models.TaskQueuePOSTResponse[source]
Parameters
  • meta (ResponsePOSTMeta) – Standard Fractal Server response metadata for POST/add type requests.

  • data (ComputeResponse) – Data returned from the server from adding a Task.

class qcportal.models.rest_models.TaskQueuePUTBody[source]
Parameters
  • meta (Meta) – The instructions to pass to the target Task from data.

  • data (Data) – The information which contains the Task target in the database.

class qcportal.models.rest_models.TaskQueuePUTResponse[source]
Parameters
  • meta (ResponseMeta) – Standard Fractal Server response metadata

  • data (Data) – Information returned from attempting updates of Tasks.

Service Queue

class qcportal.models.rest_models.ServiceQueueGETBody[source]
Parameters
  • meta (QueryMeta, Optional) – Standard Fractal Server metadata for Database queries containing pagination information

  • data (Data) – The keys with data to search the database on for Services.

class qcportal.models.rest_models.ServiceQueueGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (List[Dict[str, Union[Any, NoneType]]]) – The return of Services found in the database mapping their Ids to the Service spec.

class qcportal.models.rest_models.ServiceQueuePOSTBody[source]
Parameters
  • meta (Meta) – Metadata information for the Service for the Tag and Priority of Tasks this Service will create.

  • data (List[Union[TorsionDriveInput, GridOptimizationInput]]) – A list the specification for Procedures this Service will manage and generate Tasks for.

class qcportal.models.rest_models.ServiceQueuePOSTResponse[source]
Parameters
  • meta (ResponsePOSTMeta) – Standard Fractal Server response metadata for POST/add type requests.

  • data (ComputeResponse) – Data returned from the server from adding a Service.

class qcportal.models.rest_models.ServiceQueuePUTBody[source]
Parameters
  • meta (Meta) – The instructions to pass to the targeted Service.

  • data (Data) – The information which contains the Service target in the database.

class qcportal.models.rest_models.ServiceQueuePUTResponse[source]
Parameters
  • meta (ResponseMeta) – Standard Fractal Server response metadata

  • data (Data) – Information returned from attempting updates of Services.

Queue Manager

class qcportal.models.rest_models.QueueManagerGETBody[source]
Parameters
  • meta (QueueManagerMeta) – Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.

  • data (Data) – A model of Task request data for the Queue Manager to fetch. Accepts limit as the maximum number of tasks to pull.

class qcportal.models.rest_models.QueueManagerGETResponse[source]
Parameters
  • meta (ResponseGETMeta) – Standard Fractal Server response metadata for GET/fetch type requests.

  • data (List[Dict[str, Union[Any, NoneType]]]) – A list of tasks retrieved from the server to compute.

class qcportal.models.rest_models.QueueManagerPOSTBody[source]
Parameters
  • meta (QueueManagerMeta) – Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.

  • data (Dict[ObjectId, Any]) – A Dictionary of tasks to return to the server.

class qcportal.models.rest_models.QueueManagerPOSTResponse[source]
Parameters
  • meta (ResponsePOSTMeta) – Standard Fractal Server response metadata for POST/add type requests.

  • data (bool) – A True/False return on if the server accepted the returned tasks.

class qcportal.models.rest_models.QueueManagerPUTBody[source]
Parameters
  • meta (QueueManagerMeta) – Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.

  • data (Data) – The update action which the Queue Manager requests the Server take with respect to how the Queue Manager is tracked.

class qcportal.models.rest_models.QueueManagerPUTResponse[source]
Parameters
  • meta (Dict[str, Any], Default: {}) – There is no metadata accepted, so an empty metadata is sent for completion.

  • data (Union[name=’data_Dict[str, int]’ type=Mapping[str, int] required=True, bool]) – The response from the Server attempting to update the Queue Manager’s server-side status. Response type is a function of the operation made from the PUT request.

Common REST Components

These are NOT complete Body or Responses to the REST API, but common fragments which make up things like the Metadata or the Data fields.

class qcportal.models.rest_models.EmptyMeta[source]

There is no metadata accepted, so an empty metadata is sent for completion.

class qcportal.models.rest_models.ResponseMeta[source]

Standard Fractal Server response metadata

Parameters
  • errors (List[Tuple[str, str]]) – A list of error pairs in the form of [(error type, error message), …]

  • success (bool) – Indicates if the passed information was successful in its duties. This is contextual to the data being passed in.

  • error_description (Union[str, bool]) – Details about the error if success is False, otherwise this is False in the event of no errors.

class qcportal.models.rest_models.ResponseGETMeta[source]

Standard Fractal Server response metadata for GET/fetch type requests.

Parameters
  • errors (List[Tuple[str, str]]) – A list of error pairs in the form of [(error type, error message), …]

  • success (bool) – Indicates if the passed information was successful in its duties. This is contextual to the data being passed in.

  • error_description (Union[str, bool]) – Details about the error if success is False, otherwise this is False in the event of no errors.

  • missing (List[str]) – The Id’s of the objects which were not found in the database.

  • n_found (int) – The number of entries which were already found in the database from the set which was provided.

class qcportal.models.rest_models.ResponsePOSTMeta[source]

Standard Fractal Server response metadata for POST/add type requests.

Parameters
  • errors (List[Tuple[str, str]]) – A list of error pairs in the form of [(error type, error message), …]

  • success (bool) – Indicates if the passed information was successful in its duties. This is contextual to the data being passed in.

  • error_description (Union[str, bool]) – Details about the error if success is False, otherwise this is False in the event of no errors.

  • n_inserted (int) – The number of new objects amongst the inputs which did not exist already, and are now in the database.

  • duplicates (Union[List[str], List[Tuple[str, str]]]) – The Ids of the objects which already exist in the database amongst the set which were passed in.

  • validation_errors (List[str]) – All errors with validating submitted objects will be documented here.

class qcportal.models.rest_models.QueryMeta[source]

Standard Fractal Server metadata for Database queries containing pagination information

Parameters
  • limit (int, Optional) – Limit to the number of objects which can be returned with this query.

  • skip (int, Default: 0) – The number of records to skip on the query.

class qcportal.models.rest_models.QueueManagerMeta[source]

Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.

Parameters
  • cluster (str) – The Name of the Cluster the Queue Manager is running on.

  • hostname (str) – Hostname of the machine the Queue Manager is running on.

  • uuid (str) – A UUID assigned to the QueueManager to uniquely identify it.

  • username (str, Optional) – Fractal Username the Manager is being executed under.

  • qcengine_version (str) – Version of QCEngine which the Manager has access to.

  • manager_version (str) – Version of the QueueManager (Fractal) which is getting and returning Jobs.

  • programs (List[str]) – A list of programs which the QueueManager, and thus QCEngine, has access to. Affects which Tasks the Manager can pull.

  • procedures (List[str]) – A list of procedures which the QueueManager has access to. Affects which Tasks the Manager can pull.

  • tag (str, Optional) – Optional queue tag to pull Tasks from.

  • total_worker_walltime (float, Optional) – The total worker walltime in core-hours.

  • total_task_walltime (float, Optional) – The total task walltime in core-hours.

  • active_tasks (int, Optional) – The total number of active running tasks.

  • active_cores (int, Optional) – The total number of active cores.

  • active_memory (float, Optional) – The total amount of active memory in GB.