Home > Cloud Cruiser 4 > REST API reference > About the API

About the API

This article provides high-level information about the REST 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/v2/.
  • 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 v2.
  • The Cloud Cruiser REST API Java binding package names start with com.cloudcruiser.server.webservices.v2.
  • 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.

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 items
  • POST for creating new items and performing various tasks based on the provided request payload, such as importing services or users and retrieving billing projections
  • DELETE for deleting existing items

Authentication

As of Cloud Cruiser 4.2.8, the API supports authentication through SSO. If you have configured Cloud Cruiser to use SSO, no special authentication is required for the API. For more information about configuring SSO, see SSO authentication.

If you are not using SSO, authentication is enforced when 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:

Version 4.0
Version 4.1 and later
  • All methods: <ccServerURL>/rest/?_wadl
  • Customers: <ccServerURL>/rest/v2/customers?_wadl
  • Lookups: <ccServerURL>/rest/v2/lookups?_wadl
  • Discounts: <ccServerURL>/rest/v2/discounts?_wadl
  • Publishing usage data: <ccServerURL>/rest/v2/usages?_wadl
  • Rates: <ccServerURL>/rest/v2/ratePlans?_wadl
  • Reports: <ccServerURL>/rest/v2/reports?_wadl
  • Services: <ccServerURL>/rest/v2/serviceCatalog?_wadl
  • Users and user groups: <ccServerURL>/rest/v2/ccusers?_wadl
  • Windows Azure Pack (unsupported): <ccServerURL>/rest/v2/wap?_wadl

Paging

Paging controls are available for the REST API methods that retrieve 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 users and 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 example:

http://localhost:8080/rest/v2/serviceCatalog/summaries?startFrom=5&count=2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<serviceSummaryList xmlns="http://www.cloudcruiser.com/webservices/v2/Service" totalServices="202" retrievedServices="2" startFrom="5">
  <serviceSummary id="10004">
    <serviceName>BASIC.A1 VM (Non-Windows) - US West</serviceName>
    <groupName>APC</groupName>
    <description>Compute</description>
    <active>true</active>
    <valid>true</valid>
  </serviceSummary>
  <serviceSummary id="10005">
    <serviceName>BASIC.A1 VM (Windows) - US South Central</serviceName>
    <groupName>APC</groupName>
    <description>Compute</description>
    <active>true</active>
    <valid>true</valid>
  </serviceSummary>
</serviceSummaryList>

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 example:

http://localhost:8080/rest/v2/serviceCatalog/summaries?startFrom=300&count=2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<serviceSummaryList xmlns="http://www.cloudcruiser.com/webservices/v2/Service" totalServices="202" retrievedServices="0" startFrom="300"/>
Last modified

Tags

Classifications

This page has no classifications.
© Copyright 2018 Hewlett Packard Enterprise Development LP