RESTful web services provide a simple, URI-based means for accessing resources. You can use RESTful web services to browse resources and to perform limited operations:
The following sections highlight key features.
You can browse the following resources by using HTTP, or by using the BLCLI:
For more information, see:
You can perform the following operations:
For more information, see Performing operations on an asset. You can use RESTful web services to view resource information using HTTP, for example, within a browser.
The following sections explain how to use HTTP with RESTful web services.
The general syntax for accessing a resource using a browser is:
https://ApplicationServer:port/URI?credentials
For example:
https://myAppServer:9843/type/PropertySetClasses/SystemObject/Server/?username=BLAdmin&password=foo&role=BLAdmins
https://localhost:9843/group/Jobs/test/FileDeployExampleJob/Operations/execute?username=BLAdmin&password=""&role=BLAdmins
In the first example, the URI component for listing all servers is:
/type/PropertySetClasses/SystemObject/Server/
In the second example, the URI component for executing the Deploy Job is:/group/Jobs/test/FileDeployExampleJob/Operations/execute
For a complete description of URI syntax options, see URI syntax overview.
In the first example, the credentials component is:
username=BLAdmin&password=foo&role=BLAdmins
When you pass in a RESTful request in a browser, you must pass in a username, a password, and role credentials with each request. However, if you are submitting RESTful requests by building your own HTTPRequests from your own client, you can use the login
command to obtain a session ID. After you have a session ID, you can reuse it in subsequent requests.
For information about using a session ID, see Credentials for submitting RESTful commands.
When you pass in a RESTful request in a browser, the response is formatted as XML.
However, if you are submitting RESTful requests by building your own HTTPRequests from your own client, you can use the Accept
field to set the response type to JSON (Java Script Object Notation) or XML. For information about setting RESTful response types, see RESTful response types.
A RESTful request can produce a large number of results. For any request, you can specify the maximum number of results and where the results start. You can also specify the sort order.
For example, the following request uses the maxResults
argument to set the maximum number of results to 5:
https://myAppServer:9843/type/PropertySetClasses/SystemObject/Server/?maxResults=5&username=BLAdmin&password=foo&role=BLAdmins
For information about using paging and ordering arguments, see Paging and ordering results for a RESTful request.
You can add query statements to a RESTful request. The query statements indicate that the results must match a specified property condition. For information about using query statements, see Querying on a condition.
You can execute RESTful commands using the BLCLI. This can simplify tasks. Using RESTful commands can:
Currently, BMC Server Automation supports one RESTful command:
get
Future releases plan to support additional commands such as create
and update
.
The following sample session highlights key features.
blcli -rr JSON
get
command is:get URI
blcli get /type/PropertySetClasses/SystemObject/Server/
URI component: In this example, the URI component for listing all servers is:
/type/PropertySetClasses/SystemObject/Server/
For a complete description of URI syntax options, see URI syntax overview.
Note
If the URI in the blcli get
command contains a query string introduced by the BQUERY
keyword, enclose the full URI in double quotes.
Escape any other double quotes within the URI with backslashes. Double quotes are necessary within the URI, for example, around properties that begin with a number or special character.
For example:
blcli get "/group/Servers/0A/?maxResults=50&BQUERY=SELECT \"0s1\" FROM SystemObject/Server"
DBKey to URI: If you have an object's DBKey, you can use the BLCLI command
GenericObject : getRESTfulURI
to obtain the object's URI. After you have the URI, you can pass it in with a RESTful get command.
Pseudocode example:
//Get the DBKey of a Snapshot Job JOB_FOLDER="/SnapshotJobs" JOB_NAME="Snapshot all Servers" JOB_KEY=`blcli SnapshotJob getDBKeyByGroupAndName "$JOB_FOLDER" "$JOB_NAME"` //Get the RESTful URI of the Snapshot Job URI=`blcli GenericObject getRESTfulURI "$JOB_KEY"` //Display the Snapshot Job using the URI blcli get "$URI"
A URI (Uniform Resource Identifier) uniquely identifies a resource or list of resources.
Each URI starts with one of the following prefixes: