About the API

Conventions

• You can access the REST API by using either HTTP or HTTPS. If you want more secure access, use HTTPS.
• The base URL of the REST API resources is <ccServerURL>/rest/v1/.
• Unless otherwise noted, all URLs are case-sensitive.
• Versioning is built into the REST API URLs and the Java binding package names. The current version is v1.
• HTTP status codes and error messages are returned in the REST responses to show whether the requested operation succeeded or failed. The ServiceException failure messages are included in the response body if there are any.
• The Cloud Cruiser REST API Java binding package names start with com.cloudcruiser.server.webservices.v1.

HTTP and HTTPS methods

All REST API methods accept both HTTP and HTTPS URLs. Before you can use HTTPS, you must configure secure access to Cloud Cruiser.

The API uses the following HTTP/HTTPS methods:

• GET for retrieving summary or detailed information
• PUT for modifying and updating existing resources, resource revisions, users, and user groups.
• POST for creating new resources, users/user groups, and performing various tasks based on the provided request payload, such as importing resources or users, and retrieving billing projections, reports, etc.
• DELETE for deleting existing resources, resource revisions, users, and user groups.

Authentication

Authentication is enforced for using the Cloud Cruiser REST API. Each HTTP service request needs to provide valid user credential information by using the HTTP Authorization header with the user credential in BASIC Authentication format.

The REST API does not require the HTTP client to use an HTTP session. Each service request is stateless.

WADL documentation

The following WADL documents, accessible from your browser, provide detail about specific methods in the Cloud Cruiser REST API:

• Budgets and alerts: <ccServerURL>/rest/v1/budgets?_wadl
• Customers: <ccServerURL>/rest/v1/customers?_wadl
• Projecting charges: <ccServerURL>/rest/v1/charge?_wadl
• Publishing usage data: <ccServerURL>/rest/v1/usage?_wadl
• Rate plans: <ccServerURL>/rest/v1/ratePlans?_wadl
• Reports: <ccServerURL>/rest/v1/reports?_wadl
• Resources: <ccServerURL>/rest/v1/resources?_wadl
• Users and user groups: <ccServerURL>/rest/v1/users?_wadl

Paging

Paging controls are available for the REST API methods that retrieve resource or user summaries. All the retrieved resource summaries are ordered by their output_order in your Cloud Cruiser database tables. The paging controls are specified as query parameters in the REST URL: ?startFrom=<x>&count=<y>

• startFrom: The starting item index from which to fetch. The default value is 1.
• count: The number of items to fetch. A negative value fetches all the available items from the startFrom index. The default count is -1.

The above parameters and the total count of resources or groups available in the Cloud Cruiser database are shown as attributes in the root element of the corresponding REST XML response, as shown in the following examples:

• http://localhost:8080/rest/v1/resources?startFrom=3&count=2

  <?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
  <resources xmlns="http://www.cloudcruiser.com/webservices/v1/Resource” totalGroups="18" retrievedGroups="2" startFrom="3">
    <group id="1" totalResources="30">
      <name>VMware vCenter</name>
      <resource id="10011">
      ...
    </group>
    <group id="26" totalResources="6">
      <name>Application Services</name>
      <resource id="10123">
      ...
    </group>
  </resources>
  

• http://localhost:8080/rest/v1/resources/group/1?startFrom=3&count=2

  <?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
  <resourceGroup xmlns="http://www.cloudcruiser.com/webservices/v1/Resource" id="1" totalResources="30" retrievedResources="3" startFrom="2">
    <name>VMware vCenter</name>
    <resource id="10013">
      ...
    </resource>
    <resource id="10014">
    ...
    </resource>
  </resourceGroup>
  

• http://localhost:8080/rest/v1/users?startFrom=5&count=2

  <?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
  <users xmlns="http://www.cloudcruiser.com/webservices/v1/User" totalGroups="37" retrievedGroups="2" startFrom="5">
    <userGroup name="buCgroup" id="7" totalUsers="2">
      <user name="buCuser" id="6"/>
      <user name="buCanalyst" id="28"/>
    </userGroup>
    <userGroup name="buDgroup" id="8" totalUsers="1">
      <user name="buDuser" id="7"/>
    </userGroup>
  </users>
  

If you specify a startFrom value greater than the total number of items available in the database, the response will include 0 retrieved items, as shown in the following examples:

• http://localhost:8080/rest/v1/resources?startFrom=20&count=2

  <?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
  <resources xmlns="http://www.cloudcruiser.com/webservices/v1/Resource" totalGroups="18" retrievedGroups="0" startFrom="20"/>
  

• http://localhost:8080/rest/v1/resources?startFrom=20&count=2

  <?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
  <resourceGroup xmlns="http://www.cloudcruiser.com/webservices/v1/Resource" name="VMware vCenter" id="1" totalResources="30" retrievedResources="0" startFrom="31"/>