REST Overview

REST Overview
Jobs	Job Reports	Groups	Pools	Limits	Repository	Pulse	Workers	Tasks	Task Reports	Users

Overview

The RESTful HTTP API can be used to interact with an instance of the Web Service.

HTTP requests can be made to

• Request information from the database,

• Store new data,

• Alter existing data, or

• Remove entries from the database.

Requests to the API can be categorized by

• The type of data you are attempting to access, and by

• The type of HTTP request you are using to access the data. See Request Formats and Responses below for details.

In order to use the HTTP API, you must have the Web Service running on a machine whose address and port number you know.

Note

As all communication to Deadline travels through the machine running the Web Service and not the local host, there are consequences that should be considered carefully.

Any file paths provided need to be valid on the Web Service machine, including any differences between operating systems, if for example your local host is running Windows but the Web Service machine is running Linux.

In the case of submitting a Job, the Job’s UserName will be the user account currently running the Web Service, NOT the submitting local user, unless a UserName is provided in the Job info.

• Requests that alter data are primarily POST or PUT messages, and they typically return text stating whether they succeeded or if there was an error.

• Requests made to retrieve data are done using GET messages, and return JavaScript Object Notation (JSON) formatted objects if successful, and text explaining the error if not.

• Some POST and PUT messages will return JSON objects as well, but usually only if there is information about the action that the user may need (an example of this would be a request to create a new object, the object’s primary key may be returned on creation).

• Requests made to remove data are typically done using DELETE messages and return text stating whether they succeeded or if there was an error, just like POST and PUT messages.

• In the event of an error message being returned, the HTTP Status Code will also be set to describe the error.

Request Types

• Jobs

• Job Reports

• Groups

• Pools

• Limits

• Repository

• Pulse

• Workers

• Tasks

• Task Reports

• Users

Request Formats and Responses

• GET

  • Request for some data.

  • These messages are constructed entirely within the URL.

  • Successful requests will usually return a JSON object and failed requests will return a brief error message along with the HTTP Status Code.

  • There are some GET requests that will return plain text for a successful request.

• PUT

  • Typically a request to modify some data.

  • These messages use the URL to specify what type of data that you wish to alter, and use the message body for storing the message to the database.

  • The message body must be a JSON object, although how this object must be built depends on the data being modified.

  • PUT messages for data that does not exist will often fail, but in some cases will act as a POST.

  • Successful requests will usually return text stating success. Failed requests will return a brief error message along with the HTTP Status Code.

  • There are some PUT messages that return JSON objects, and this usually occurs when data has been created instead of altered.

• POST

  • Request to create some data.

  • These messages use the URL to specify what type of data that you wish to create, and use the message body for storing the message to the database.

  • The message body must be a JSON object, although how this object must be built depends on the data being modified.

  • POST messages for data that already exists will fail.

  • Successful requests will usually return text stating success.

  • Failed requests will return a brief error message along with the HTTP Status Code.

  • There are some POST messages that return JSON objects.

• DELETE

  • Request to delete some data.

  • These messages are constructed entirely within the URL.

  • Successful requests will usually return text stating success.

  • Failed requests will return a brief error message along with the HTTP Status Code.

HTTP Status Codes

The following are the HTTP Status Code that can be returned, and what they signify in Deadline.

• 200 - OK

  Request completed without error. Note that this does not always mean the request modified everything as intended. Example: trying to send a “complete” message to a completed job will do nothing and return this status code. Another example: trying to release a job from pending when the job is not pending will return this status code and do nothing.

• 400 - Bad Request

  Request could not be completed due to incorrect request message structure in either the URL or the body of the request message.

• 404 - Not Found

  Requested data could not be found, or requested command could not be found.

• 405 - Method Not Allowed

  Requested operation could not be completed using the request format given.

• 500 - Internal Server Error

  Request message could not be interpreted properly, or the action being attempted causing an exception in Deadline.

• 501 - Not Implemented

  Request type is not supported. For example, a JobReport PUT request would return this because only GET is supported.

Additional Information

If a request is made for a JSON object, and an empty JSON object is returned, then the information provided for the request did not match any entry in the repository.

Adding additional key-value pairs to a JSON object for a request that does not specify their use can have surprising consequences. Keys that are not used by other commands will be ignored, but be sure to read the documentation for each possible query for each request type before building a JSON object for your query, as some commands are identical other than the presence of a single key and have vastly different effects.

If a documented query requires a JSON object that you do not know how to properly construct, it is often possible to do a GET query for the same object type and receive the JSON format that the query expects.

A query that returns “Success” does not imply that the actions your query requested occurred. Some actions are impossible, but do not warrant an error message. (Example, sending a Suspend message to a Suspended job, or Deleting a Worker that does not exist or was already Deleted.)