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

page
  • Description: The total number of pages in for the API listing.

    • Default = 0

    • If size=0, then the page value is ignored.

    • If not specified (page=0&size=20), the default size (default = 20) value displays the first 20 elements, which is equal to one page
    • If you specify both the page and the size values, the following applies:

      If you specify......then
      size=21Elements numbered 21 - 40 entities are displayed, which is equal to 2 pages
      page=0
      (or not specified)
      The first set of 20 elements in the list, elements 1 to 20 are displayed
      page=1The second set of 20 elements in the list, elements 21 to 40 are displayed
      page=2

      The third set of 20 elements in the list (the third page).

      if the page does not have more than 10 elements, then only those 10 elements are displayed.

      page=1&&size=10A set of 10 elements, Elements 11 to 20 are displayed
      page=1&&size=20A set of 20 elements, Elements 21 to 40 are displayed
      page=2&&size=10A set of 10 elements, Elements 21 to 30 are displayed
  • Type: Integer
size
  • Description: Total number of records that any list page should contain. The default is: 

    • v1 APIs = 20 records

    • v2 APIs = 50 records

  • Type: Integer

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 (minus) 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=[attributeorder]

      • 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

          EnumerationDescription
          SUBMITTEDThe operation has been submitted
          RUNNINGThe operation is currently in progress
          SUCCESSThe operation succeeded
          FAILThe 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 ResourceValid 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. 

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

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

  • No labels
© 2017-2019 Cisco Systems, Inc. All rights reserved