REST Overview

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 said data. 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 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 or 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 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.)