Running REST commands

Many different programs can run REST commands. To run the command, you call a method on a REST resource and pass parameters or a request in JSON format.

Note: Using REST commands requires the same permissions as using the web interface. For information about permissions, see Roles and permissions.

Example: Running simple REST commands with curl

The Linux™ program curl is a simple way to run REST commands. To run a REST command, put together the URL of one of the REST resources, specify the method to use, and add any parameters. For example, the following curl command retrieves a list of all initiatives. The command calls the GET method of the agent resource:

curl -k -u jsmith:passw0rd 
  https://hostname:port/agents/ 
  -X GET -H "Accept: application/json"

Note: You must enter this command on a single line. It is split onto different lines here for clarity.

Note: This example uses the -k switch to connect to the server without checking SSL certificate validity. To set up authentication, see Authenticating for REST commands.

This example uses the user name jsmith and the password passw0rd. In most cases, create a dedicated user account for the REST commands to use and give that account the appropriate permissions.

Use the host name and port of your server for hostname and port. For example, if the host name is ubuild.example.org and the port is the default value of 8080, the curl command might look like the following example:

curl -k -u jsmith:passw0rd 
  https://ubuild.example.org:8080/jobs/ 
  -X GET -H "Accept: application/json"

The response for this command is a JSONArray list of all jobs on the server, as in the following example:

[
  {
        "id": 32,
        "name": "Ant Build Job",
        "active": true,
        "description": null,
        "location": "/rest2/jobs/32"
    },
    {
        "id": 31,
        "name": "Demo Job",
        "active": true,
        "description": null,
        "location": "/rest2/jobs/31"
    },
]

Passing parameters to REST commands

Many REST commands have one or more parameters. Some parameters are added to the base of the URL and others are added at the end of the URL.

For example, the GET method of the /jobs/{id} resource returns information about a job. This method has a parameter in the base of its URL. The parameter {id} refers to the ID of a job. To use the GET method of this resource, you must substitute the ID of a job in the URL. For example, if the initiative ID is 31, you might run the following command:

curl -k -u jsmith:passw0rd 
  https://ubuild.example.org:8080/jobs/31/ 
  -X GET -H "Accept: application/json"

Some methods accept parameters at the end of the URL. For example, the GET method of the projects resource accepts the format parameter. This parameter specifies the format of the returned JSON. For example, to show additional detail about the projetcs on the server, pass the value detail to the format parameter, as in the following example:

curl -k -u jsmith:passw0rd 
  https://ubuild.example.org:8080/projects/
  ?format=detail 
  -X GET -H "Accept: application/json"

The resulting JSON code is more detailed than if you omitted the parameter.

Note: All parameter values must be URL encoded. For example, if a parameter includes a space, you must substitute the URL encoded value %20.

Passing JSON strings to commands

For more complex commands, you must send a JSON string or file instead of or in addition to the parameters.

For example, the POST method of the initiatives resource creates an initiative. To use this command, you must pass a JSON string that specifies the name and description of the new initiative. The JSON string for this command must follow this template:

{
  "name": "Initiative name",
  "description": "Initiative description"
}

This template is listed in the reference information for the command. See REST commands.

To pass this JSON string to the projects resource, you can either save the string to a file or include it in the command. For example, if you save the string to a file that is named newProject.json, the command looks like the following example:

curl -k -u jsmith:passw0rd 
  https://ubuild.example.org:8080/projects/
  -d @newProjects.json 
  -X POST -H "Content-Type: application/json"

You can also pass the string directly to the command, as shown in the following example:

curl -k -u jsmith:passw0rd 
  https://ubuild.example.org:8080/projects/
  -d '{"name":"myProject","description":"My New Project"}' 
  -X POST -H "Content-Type: application/json"

Note: The string that you pass to the command must be a valid JSON string.

Responses

After a successful command, most commands return either a simple string value or a JSON string.

In addition to the result of the command, the commands return standard HTTP status codes. The following list includes the most common status codes that REST commands return.

200

The command was successful.

400

You do not have permission to run the command.
You did not specify a required parameter.
The resource path in the URL is incorrect.

404

The object that you are trying to retrieve does not exist.

405

The HTTP method name is incorrect.

415

The content type in the request header is incorrect.

500

The server encountered an error.