CloudCenter Suite API Overview

Overview

The payloads for the CloudCenter Suite APIs are visible in the API documentation section for each module.

CloudCenter Suite API Version

CloudCenter Suite APIs provide support for the CloudCenter Suite modules: Suite Admin API, Workload Manager API, Action Orchestrator API, and Cost Optimizer API.

The User, Groups, and Tenant APIs are part of the Suite Admin and each API using these services have an additional prefix in the URI. The payloads for the CloudCenter Suite APIs are visible the API documentation section for each module. 

The v2 APIs, where available, provide structured responses with minimum details and provides links for nested resources as well as improved search, sort, and pagination filters.

Date Format

The CloudCenter Suite API date and time values are formatted in Unix time to the millisecond level. The APIs are agnostic to dates and time zones.

HTTPS Request Methods

CloudCenter Suite APIs support the following request methods:

• GET: To query or view the server information based on a CloudCenter Suite deployment
• PUT: To replace the entire object for update operations
• POST: To perform a CloudCenter Suite task or creating the resource
• DELETE: To remove specific aspects of the CloudCenter Suite deployment

Response Schema

CloudCenter APIs issue responses for all APIs using both JSON and XML formats. You can set the response format by sending the appropriate Content-Type request headers:

• JSON (Default)

  Content-Type: application/json Accept: application/json

• XML

  Content-Type: application/xml Accept: application/xml

  
  

• CSV (Only for Reports)

  The CSV format only applies to report-based APIs

  Content-Type: application/csv Accept: text/csv

Resource URL and ID

For each API request, you see two common attributes displayed in the API response:

• The resource URL: A unique URL that provides access to the requested CloudCenter Suite Resource.

• The POST and PUT API calls additionally provide an id attribute for each new CloudCenter Suite Resource.

Pagination

The pagination information differs based on the API version:

• v1 APIs: The GET (view or list) APIs support pagination by default. CloudCenter Suite APIs use the following attributes to provide paginated results:

  

• v2 APIs: Requires the page and size attributes for any request. The default size for v2 APIs now list 50 records by default.

Pagination Request Attributes

Pagination Response Attributes

• v1 APIs: 

  pageResource

  • Description: Identifies the pagination information for each resource

  • Type: Sequence of attributes for v1 APIs

    size (see above)

    pageNumber Description: The page number that the client wants to fetch. Page numbers start with 0 (default). Type: Integer

    totalElements Description: The number resources that an API call returns Type: Long

    totalPages Description: The number of pages in a response  Type: Integer

• v2 APIs: 

  pageResource

  • Description: Identifies the pagination information for each resource

  • Type: Sequence of attributes for v2 APIs

    resource Description: Unique URL to access this resource. Type: String

    size (see above)

    pageNumber Description: The page number that the client wants to fetch. Page numbers start with 0 (default). Type: Integer

    totalPages Description: The number of pages in a response  Type: Integer

    jobs Description: Array of JSON objects that use jobs as the key.                                                                   Type: Array of JSON objects

    previousPage Description: A resource link to the previous page. Type: URI as a string

    nextPage Description: A resource link to the following page. Type: URI as a string

    lastPage Description: A resource link to the last page. Type: URI as a string

Sorting

• v1 APIs: All list APIs support sorting by default and use the query-string parameters to provide sorted results with a comma-separated set of property names.

  • Sorting Order:

    • Ascending order: Default when you specify the property.

    • Descending order: Append a dash  to the property.

  • Example:

    • sort=id,name: Sort by ID property in ascending order and then sort by name property in ascending order.

    • sort=id,name-,description: Sort by ID property in ascending order, then sort by name property in descending order, and finally sort by description in ascending order.

  • Property name validation: Property names in sort parameters are validated. For example, APIs that return a list of users can sort only on properties exposed by the user object as sortable.

  • The following example displays the use of sorting and pagination attributes in the same API request.

    

• v2 APIs: Requires the sort attributes for any request. 

  sort

  • Description: Sorts API responses based on the format specified.
  • Type: String
    
    • Sorting order:
      
      • Ascending order = ASC
      • Descending order = DESC
    • Default: Sort criteria is based on startTime and DESC order.
    • Format: sort=[attribute, order]
    • Example: [endTime,ASC]

    • Sorting attributes:

      id Description: Unique, system-generated identifier for this resource. Type: String

      status Description: Status of the operation. See the APIs for the relevant module to view a list of all job operations. Type: Enumeration Enumeration Description SUBMITTED The operation has been submitted RUNNING The operation is currently in progress SUCCESS The operation succeeded FAIL The operation failed

      startTime/endTime Description: Start/End time for this resource. Unix epoch time in milliseconds. Type:  v1 APIs = Long v2 APIs = Epoch time as a String

      totalCost Description: Identifies the total cost per hour of the job for billing purposes. See the Cost Optimizer APIs section to view additional details. Type: Float

      nodeHours Description: The number of VM hours for this resource. See the Cost Optimizer APIs section to view additional details. Type: Float

      name Description: The name assigned for this CloudCenter Suite Resource. Valid characters are letters, numbers, underscores, and spaces. Type: String

      deploymentEntity.name Description: Identifies evolving resource details about the deployment. The deploymentEntity attribute uses the deploymentEntity.name format, where .name is a search value for deploymentEntity and deploymentEntity itself is a JSON object. Instead of placing the deployment name at the top level search and adding numerous query parameters, this format allows for nested search results. The top level name is the job name and deploymentEntity.name is the deployment name. Type: JSON objects

      favoriteCreationTime Description: If the job was configured as a favorite job, then this attribute identifies the time when this configuration took place. See the Favorite Deployments section for the relevant release for additional context. Type: Epoch time as a String

Searching

This attribute is only available for v2 APIs. 

search

• Description: Searches API responses based on the format specified.
• Type: String
  
  • Format: search=[field, searchType, SearchExpression1, SearchExpression2 ]

  • Example: search =[startTime, gt, 01/01/2016]

  • Search Expressions:

    • pattern: Provide a pattern using the format provided in the searchTypes table below.

    • searchTypes

      searchType	Format
      eq	==
      ne	!=
      el	LIKE pattern%
      fl	LIKE %pattern
      eln	NOT LIKE pattern%
      fln	NOT LIKE %pattern
      fle	LIKE %pattern%"
      gt	> searchValue
      lt	< searchValue
      ge	>= searchValue
      le	<= searchValue
      gtlt	> searchValue && searchValue
      gtelt	>= searchValue && < searchValue
      gtlte	> searchValue && <= searchValue
      gtelte	>= searchValue && <= searchValue
      emp	Empty string
      noemp	Not Empty string
      nu	Null value
      nn	Not Null Value

    • searchValue:
      

      searchValue	SearchType Availability
      id	eq
      startTime	eq, nu, gtlt
      endTime	eq, nu, nn, gtlt
      totalCost	eq, gt, ge, le, gtlt, gtlte, gtelte, gtelt
      favoriteCreationTime	eq, nu, ,nn gtlt
      jobStatusMessage	el, eln, fl, fln, fle, nn, emp, noemp
      nodeHours	eq, gt, ge, le, gtlt, gtlte, gtelte, gtelt
      name	eq, nn, eln, fle, fln, el, emp, noemp, fl
      description	eq, nn, eln, fle, fln, el, emp, noemp, fl
      deploymentEntity.name	eq, nn, eln, fle, fln, el, emp, noemp, fl
      ownerEmailAddress	eq
      cloudFamily	eq, nu
      status	eq, nu

HTTP Location URL

The HTTP Status code and the Location URL (highlighted in blue in the following example) is provided in the Response Header when Create resource API calls are successful:

Who Can Use CloudCenter Suite APIs?

Both admins and users can use CloudCenter Suite REST APIs. 

Your login credentials determine if you are an admin (platform (root), tenant admin, or co-admin) or a user. If you do not have the required Permission Control level to access any resource, you receive the HTTP 403 status error mentioned in the HTTP Status Codes section.