Testbed REST API Reference#

Note

See the Glossary for the meaning of the acronyms used in this guide.

This page documents the endpoints and available HTTP methods for the Dioptra REST API. In addition to using this page, it is highly recommended that Testbed users also use the Swagger documentation that the REST API service automatically generates at runtime, which presents all of this page’s information in an interactive format. To access the Swagger documentation, just navigate to the web URL for the Testbed REST API service (omit the /api part at the end of the web address).

An animation clicking and scrolling through the contents of the Dioptra :term:`REST` :term:`API` Swagger documentation.

An animated tour of the automatically generated Swagger documentation for the Dioptra REST API. Several of the Testbed demos that you can run on a personal computer publish the REST API service at the address http://localhost:30080.#

Experiment#

Experiment registration operations.

Endpoints#

The following is the list of endpoints under the /api/experiment/ namespace.

GET /api/experiment/#

Gets a list of all registered experiments

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • [].createdOn (string) – The date and time the experiment was created.

  • [].experimentId (integer) – An integer identifying a registered experiment.

  • [].lastModified (string) – The date and time the experiment was last modified.

  • [].name (string) – The name of the experiment.

POST /api/experiment/#

Creates a new experiment via an experiment registration form

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Form Parameters

  • name – (required) The name to register as a new experiment.

Response JSON Object

  • createdOn (string) – The date and time the experiment was created.

  • experimentId (integer) – An integer identifying a registered experiment.

  • lastModified (string) – The date and time the experiment was last modified.

  • name (string) – The name of the experiment.

DELETE /api/experiment/{experimentId}#

Deletes an experiment by its unique identifier

Parameters

  • experimentId (integer) – An integer identifying a registered experiment.

Status Codes
GET /api/experiment/{experimentId}#

Gets an experiment by its unique identifier

Parameters

  • experimentId (integer) – An integer identifying a registered experiment.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the experiment was created.

  • experimentId (integer) – An integer identifying a registered experiment.

  • lastModified (string) – The date and time the experiment was last modified.

  • name (string) – The name of the experiment.

PUT /api/experiment/{experimentId}#

Modifies an experiment by its unique identifier

Parameters

  • experimentId (integer) – An integer identifying a registered experiment.

Request JSON Object

  • name (string) – The new name of the experiment. Must be unique.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the experiment was created.

  • experimentId (integer) – An integer identifying a registered experiment.

  • lastModified (string) – The date and time the experiment was last modified.

  • name (string) – The name of the experiment.

DELETE /api/experiment/name/{experimentName}#

Deletes an experiment by its unique name

Parameters

  • experimentName (string) – The name of the experiment.

Status Codes
GET /api/experiment/name/{experimentName}#

Gets an experiment by its unique name

Parameters

  • experimentName (string) – The name of the experiment.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the experiment was created.

  • experimentId (integer) – An integer identifying a registered experiment.

  • lastModified (string) – The date and time the experiment was last modified.

  • name (string) – The name of the experiment.

PUT /api/experiment/name/{experimentName}#

Modifies an experiment by its unique name

Parameters

  • experimentName (string) – The name of the experiment.

Request JSON Object

  • name (string) – The new name of the experiment. Must be unique.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the experiment was created.

  • experimentId (integer) – An integer identifying a registered experiment.

  • lastModified (string) – The date and time the experiment was last modified.

  • name (string) – The name of the experiment.

Error Messages#

The following error handlers are registered to the experiment endpoints.

Job#

Job submission and management operations.

Endpoints#

The following is the list of endpoints under the /api/job/ namespace.

GET /api/job/#

Gets a list of all submitted jobs

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • [].createdOn (string) – The date and time the job was created.

  • [].dependsOn (string) – A UUID for a previously submitted job to set as a dependency for the current job.

  • [].entryPoint (string) – The name of the entry point in the MLproject file to run.

  • [].entryPointKwargs (string) – A string listing parameter values to pass to the entry point for the job. The list of parameters is specified using the following format: “-P param1=value1 -P param2=value2”.

  • [].experimentId (integer) – An integer identifying a registered experiment.

  • [].jobId (string) – A UUID that identifies the job.

  • [].lastModified (string) – The date and time the job was last modified.

  • [].mlflowRunId (string) – A UUID that identifies the MLFLow run associated with the job.

  • [].queueId (integer) – An integer identifying a registered queue.

  • [].status (string) – The current status of the job. The allowed values are: queued, started, deferred, finished, failed.

  • [].timeout (string) – The maximum alloted time for a job before it times out and is stopped.

  • [].workflowUri (string) – The URI pointing to the tarball archive or zip file uploaded with the job.

POST /api/job/#

Creates a new job via a job submission form with an attached file

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Form Parameters

  • experiment_name – (required) The name of a registered experiment.

  • queue – (required) The name of an active queue.

  • timeout – The maximum alloted time for a job before it times out and is stopped. If omitted, the job timeout will default to 24 hours.

  • entry_point – (required) The name of the entry point in the MLproject file to run.

  • entry_point_kwargs – A list of entry point parameter values to use for the job. The list is a string with the following format: “-P param1=value1 -P param2=value2”. If omitted, the default values in the MLproject file will be used.

  • depends_on – A job UUID to set as a dependency for this new job. The new job will not run until this job completes successfully. If omitted, then the new job will start as soon as computing resources are available.

  • workflow – (required) A tarball archive or zip file containing, at a minimum, a MLproject file and its associated entry point scripts.

Response JSON Object

  • createdOn (string) – The date and time the job was created.

  • dependsOn (string) – A UUID for a previously submitted job to set as a dependency for the current job.

  • entryPoint (string) – The name of the entry point in the MLproject file to run.

  • entryPointKwargs (string) – A string listing parameter values to pass to the entry point for the job. The list of parameters is specified using the following format: “-P param1=value1 -P param2=value2”.

  • experimentId (integer) – An integer identifying a registered experiment.

  • jobId (string) – A UUID that identifies the job.

  • lastModified (string) – The date and time the job was last modified.

  • mlflowRunId (string) – A UUID that identifies the MLFLow run associated with the job.

  • queueId (integer) – An integer identifying a registered queue.

  • status (string) – The current status of the job. The allowed values are: queued, started, deferred, finished, failed.

  • timeout (string) – The maximum alloted time for a job before it times out and is stopped.

  • workflowUri (string) – The URI pointing to the tarball archive or zip file uploaded with the job.

GET /api/job/{jobId}#

Gets a job by its unique identifier

Parameters

  • jobId (string) – A string specifying a job’s UUID.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the job was created.

  • dependsOn (string) – A UUID for a previously submitted job to set as a dependency for the current job.

  • entryPoint (string) – The name of the entry point in the MLproject file to run.

  • entryPointKwargs (string) – A string listing parameter values to pass to the entry point for the job. The list of parameters is specified using the following format: “-P param1=value1 -P param2=value2”.

  • experimentId (integer) – An integer identifying a registered experiment.

  • jobId (string) – A UUID that identifies the job.

  • lastModified (string) – The date and time the job was last modified.

  • mlflowRunId (string) – A UUID that identifies the MLFLow run associated with the job.

  • queueId (integer) – An integer identifying a registered queue.

  • status (string) – The current status of the job. The allowed values are: queued, started, deferred, finished, failed.

  • timeout (string) – The maximum alloted time for a job before it times out and is stopped.

  • workflowUri (string) – The URI pointing to the tarball archive or zip file uploaded with the job.

Error Messages#

The following error handlers are registered to the job endpoints.

Queue#

Queue registration operations.

Endpoints#

The following is the list of endpoints under the /api/queue/ namespace.

GET /api/queue/#

Gets a list of all registered queues

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • [].createdOn (string) – The date and time the queue was created.

  • [].lastModified (string) – The date and time the queue was last modified.

  • [].name (string) – The name of the queue.

  • [].queueId (integer) – An integer identifying a registered queue.

POST /api/queue/#

Creates a new queue via a queue registration form

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Form Parameters

  • name – (required) The name to register as a new queue.

Response JSON Object

  • createdOn (string) – The date and time the queue was created.

  • lastModified (string) – The date and time the queue was last modified.

  • name (string) – The name of the queue.

  • queueId (integer) – An integer identifying a registered queue.

DELETE /api/queue/{queueId}#

Deletes a queue by its unique identifier

Parameters

  • queueId (integer) – An integer identifying a registered queue.

Status Codes
GET /api/queue/{queueId}#

Gets a queue by its unique identifier

Parameters

  • queueId (integer) – An integer identifying a registered queue.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the queue was created.

  • lastModified (string) – The date and time the queue was last modified.

  • name (string) – The name of the queue.

  • queueId (integer) – An integer identifying a registered queue.

PUT /api/queue/{queueId}#

Modifies a queue by its unique identifier

Parameters

  • queueId (integer) – An integer identifying a registered queue.

Request JSON Object

  • name (string) – The new name for the queue. Must be unique.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the queue was created.

  • lastModified (string) – The date and time the queue was last modified.

  • name (string) – The name of the queue.

  • queueId (integer) – An integer identifying a registered queue.

DELETE /api/queue/{queueId}/lock#

Removes the lock from the queue (id reference) if it exists

Parameters

  • queueId (integer) – An integer identifying a registered queue.

Status Codes
PUT /api/queue/{queueId}/lock#

Locks the queue (id reference) if it is unlocked

Parameters

  • queueId (integer) – An integer identifying a registered queue.

Status Codes
DELETE /api/queue/name/{queueName}#

Deletes a queue by its unique name

Parameters

  • queueName (string) – The name of the queue.

Status Codes
GET /api/queue/name/{queueName}#

Gets a queue by its unique name

Parameters

  • queueName (string) – The name of the queue.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the queue was created.

  • lastModified (string) – The date and time the queue was last modified.

  • name (string) – The name of the queue.

  • queueId (integer) – An integer identifying a registered queue.

PUT /api/queue/name/{queueName}#

Modifies a queue by its unique name

Parameters

  • queueName (string) – The name of the queue.

Request JSON Object

  • name (string) – The new name for the queue. Must be unique.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • createdOn (string) – The date and time the queue was created.

  • lastModified (string) – The date and time the queue was last modified.

  • name (string) – The name of the queue.

  • queueId (integer) – An integer identifying a registered queue.

DELETE /api/queue/name/{queueName}/lock#

Removes the lock from the queue (name reference) if it exists

Parameters

  • queueName (string) – The name of the queue.

Status Codes
PUT /api/queue/name/{queueName}/lock#

Locks the queue (name reference) if it is unlocked

Parameters

  • queueName (string) – The name of the queue.

Status Codes

Error Messages#

The following error handlers are registered to the queue endpoints.

Task Plugin#

Task plugin registry operations.

Endpoints#

The following is the list of endpoints under the /api/taskPlugin/ namespace.

GET /api/taskPlugin/#

Gets a list of all registered task plugins

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • [].collection (string) – The collection that contains the task plugin module, for example, the “builtins” collection.

  • [].modules[] (string) – The available modules (Python files) in the task plugin package.

  • [].taskPluginName (string) – A unique string identifying a task plugin package within a collection.

POST /api/taskPlugin/#

Registers a new task plugin uploaded via the task plugin upload form

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Form Parameters

  • task_plugin_name – (required) A unique string identifying a task plugin package within a collection.

  • task_plugin_file – (required) A tarball archive or zip file containing a single task plugin package.

  • collection – (required) The collection where the task plugin should be stored.

Response JSON Object

  • collection (string) – The collection that contains the task plugin module, for example, the “builtins” collection.

  • modules[] (string) – The available modules (Python files) in the task plugin package.

  • taskPluginName (string) – A unique string identifying a task plugin package within a collection.

GET /api/taskPlugin/dioptra_builtins/{taskPluginName}#

Gets a builtin task plugin by its unique name

Parameters

  • taskPluginName (string) – A unique string identifying a task plugin package within dioptra_builtins collection.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • collection (string) – The collection that contains the task plugin module, for example, the “builtins” collection.

  • modules[] (string) –

  • taskPluginName (string) – A unique string identifying a task plugin package within a collection.

DELETE /api/taskPlugin/dioptra_custom/{taskPluginName}#

Deletes a custom task plugin by its unique name

Parameters

  • taskPluginName (string) – A unique string identifying a task plugin package within dioptra_custom collection.

Status Codes
GET /api/taskPlugin/dioptra_custom/{taskPluginName}#

Gets a custom task plugin by its unique name

Parameters

  • taskPluginName (string) – A unique string identifying a task plugin package within dioptra_custom collection.

Status Codes
Request Headers

  • X-Fields – An optional fields mask

Response JSON Object

  • collection (string) – The collection that contains the task plugin module, for example, the “builtins” collection.

  • modules[] (string) –

  • taskPluginName (string) – A unique string identifying a task plugin package within a collection.

Error Messages#

The following error handlers are registered to the task plugin endpoints.