Using BMC Server Automation - RESTful Web Services

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.

Browsing resources

You can browse the following resources by using HTTP, or by using the BLCLI:

• Objects identified via group paths
• Property classes
• Objects identified by object ID
• Asset classes
• Assets

For more information, see:

• To use HTTP with RESTful web services
• To execute RESTful commands using the BLCLI

Performing operations

You can perform the following operations:

• Execute a job
• Manipulate an asset that is based on a custom object

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.

Using HTTP with RESTful web services

The following sections explain how to use HTTP with RESTful web services.

General syntax

The general syntax for accessing a resource using a browser is:
https://ApplicationServer:port/URI?credentials

For example:

• To list all servers associated with an Application Server named myAppServer:
https://myAppServer:9843/type/PropertySetClasses/SystemObject/Server/?username=BLAdmin&password=foo&role=BLAdmins
• To execute a Deploy Job from an Application Server on the local host:
  https://localhost:9843/group/Jobs/test/FileDeployExampleJob/Operations/execute?username=BLAdmin&password=""&role=BLAdmins

URI component

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.

Credentials component

In the first example, the credentials component is:
username=BLAdmin&password=foo&role=BLAdmins

Credentials alternative

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.

Response format

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.

Paging and ordering

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.

Query statements

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.

Executing RESTful commands using the BLCLI

You can execute RESTful commands using the BLCLI. This can simplify tasks. Using RESTful commands can:

• Reduce the number of commands you need to use.
• Reduce reliance on DBKeys.

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.

1. Startup options for response formatting: When you start your BLCLI session, you can use options to specify the format of the RESTful response. The format can be XML or Json.
   Example:
   blcli -rr JSON
   For more information about specifying RESTful response types, see RESTful response types.
2. The general syntax for using the get command is:
   get URI
   Example: The following example lists all the servers on the Application Server associated with your BLCLI session:
   blcli get /type/PropertySetClasses/SystemObject/Server/
3. 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.

4. 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.

• URI syntax overview
• URI basic syntax rules

URI syntax diagram

URI syntax overview

Each URI starts with one of the following prefixes:

• group
  Indicates that instances or assets are being referenced by group or asset path. Sample top level groups:
  • Depot
  • Jobs
  • Components
  • Servers
  • Component Templates
  • Device
• id
  Indicates that instances or assets are being referenced by GUID.
• type
  Indicates that resources are being referenced by type. Sample top level types:
  • PropertySetClasses
  • AssetClasses
• query
  Indicates that you are selecting only those resources that meet a certain property condition.

URI basic syntax rules

• Referencing children of a resource: In general, if you want to reference the children of a resource, add a trailing slash.
  For examples of how to do this, see Property class examples and Asset examples.
• Working with assets: When working with assets, you add the following keywords to the URI syntax:
  • Assets--for retrieving assets
  • AssetAttributeValues--for retrieving attributes of an asset
  • AssetClasses--for retrieving asset classes
    For examples of how to do this, see Asset examples.
• Paging and ordering: For any request, you can specify the maximum number of results and where the results start. You can also specify the sort order.
  For information about how to add these syntax elements to a URI, see Paging and ordering results for a RESTful request.
• Working with operations: You specify the operation by ending the URI with the string "Operations/ operation_name".
  For information about how to do this, see Performing operations on an asset.
• UTF-8 encoding. You must encode URIs in UTF-8 (replacing spaces with %20, and so on).