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
initiatives resource:
curl -k -u jsmith:passw0rd
https://hostname:port/initiatives/
-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
ucrelease.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://ucrelease.example.org:8080/initiatives/
-X GET -H "Accept: application/json"
The response for
this command is a JSONArray list of all initiatives on the server,
as in the following example:
[
{
"description": "My init",
"name": "InitA",
"id": "c1e7dd8f-b1fc-41ea-8d73-a120da8d9999",
"version": 0,
"dateCreated": 1413559219120
},
{
"description": "Another init",
"name": "InitB",
"id": "30873ef0-c9f3-4af3-a4dd-eedda71c9bbf",
"version": 0,
"dateCreated": 1413559224354
}
]
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
/initiatives/{id} resource
returns information about an initiative. This method has a parameter
in the base of its URL. The parameter
{id} refers
to the ID of an initiative. To use the
GET method
of this resource, you must substitute the ID of an initiative in the
URL. For example, if the initiative ID is
c1e7dd8f-b1fc-41ea-8d73-a120da8d9999,
you might run the following command:
curl -k -u jsmith:passw0rd
https://ucrelease.example.org:8080/initiatives/
c1e7dd8f-b1fc-41ea-8d73-a120da8d9999"
-X GET -H "Accept: application/json"
Some methods
accept parameters at the end of the URL. For example, the
GET method
of the
initiatives resource accepts the
format parameter.
This parameter specifies the format of the returned JSON. For example,
to show additional detail about the initiatives on the server, pass
the value
detail to the
format parameter,
as in the following example:
curl -k -u jsmith:passw0rd
https://ucrelease.example.org:8080/initiatives/
?format=detail
-X GET -H "Accept: application/json"
The resulting JSON
code is more detailed than if you omitted the parameter. In this case,
it includes the applications, releases, and changes that are associated
with each initiative. For valid values for the
format parameter,
see the reference page for the method.
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
initiatives 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
newInitiative.json,
the command looks like the following example:
curl -k -u jsmith:passw0rd
https://ucrelease.example.org:8080/initiatives/
-d @newInitiative.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://ucrelease.example.org:8080/initiatives/
-d '{"name":"Initiative B","description":"Description of Initiative B"}'
-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.