CliQr is now part of Cisco Learn More About Cisco

CloudCenter API Overview

The CloudCenter platform uses the REST API conventions provided in this section.

CloudCenter API Version

CloudCenter API Version 1.0 (v1) provides APIs to support the following CloudCenter releases:

  • CloudCenter 4.x
  • CloudCenter 3.x

CloudCenter API Version 2.0 (v2) provides APIs to support the following CloudCenter releases:

  • CloudCenter 4.6.0 and later – identified for each API, where applicable.
  • Examples – See Report Management APIs and Job Management APIs.
  • Benefits: 
    • Structured responses with minimum details and provides links for nested job-related resources.
    • Improved search, sort, and pagination filters.
    • If a cloud region or tier is not specified in the request, those details are not displayed in the response.
    • Governance is referenced using tagIds, deployments are referenced using depEnvId, and so forth. Similarly, all other resources are referenced using the corresponding ID.

Documentation Conventions

The CloudCenter documentation uses the following conventions:

  • <Syntax> — Identifies a value that you must provide. For example, replace <HOST> with the IP address or DNS name. See Base URI Format for additional context.
  • Name — Identifies a required CloudCenter attribute name required for each API call. For example, tenant.
  • Value — Identifies a generated CloudCenter value required for each API call. For example, tenantId, is the actual value for the attribute and will be replaced by the ID (tenants/1 will indicated a tenant with the ID of 1).

Date Format

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

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 Resource.
  • The POST and PUT (see HTTPS Request Methods) API calls additionally provide an id attribute for each new CloudCenter Resource.

See Response Schema for additional context

Pagination

The pagination information differs based on the API version:

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

  • v2 APIs: Requires the page and size attributes for any request. See  View Jobs for an example.

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

      Icon

      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 elements that any list page should contain. The default is: 

    • v1 APIs = 20. 

    • v2 APIs = 0 (zero) all elements are returned and the page value is ignored.

  • Type: Integer

Pagination Response Attributes

  • v1 APIs:
    pageResource
    • Description: Identifies the pagination information for each resource
    • Type: Sequence of attributes for v1 APIs

       Click here to expand...
      size
      • Description: Total number of elements that any list page should contain. The default is: 

        • v1 APIs = 20. 

        • v2 APIs = 0 (zero) all elements are returned and the page value is ignored.

      • Type: Integer
      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

       Click here to expand...
      resource
      • Description: Unique URL to access this resource
      • Type: String
      size
      • Description: Total number of elements that any list page should contain. The default is: 

        • v1 APIs = 20. 

        • v2 APIs = 0 (zero) all elements are returned and the page value is ignored.

      • Type: Integer
      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. CloudCenter APIs 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. See View Jobs for an example.
    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
        • DescriptionUnique, system-generated identifier for this CloudCenter Resource.

        • Type: String
        status
        • Description: Status of the operation. See Deployment and VM States for 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
        totalCost
        • Description: Identifies the total cost per hour of the job for billing purposes (see CloudCenter Cost and Fees for additional details).
        • Type: Float
        nodeHours
        • Description: The number of VM hours (see Financial Overview) for this resource.
        • Type: Float
        name
        • DescriptionThe name assigned for this CloudCenter 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 search value for deploymentEntity and deploymentEntity itself is a JSON object.

          Icon

          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

          type
          • DescriptionThe type of resource
          • Type: String

          id
          • DescriptionUnique, system-generated identifier for this CloudCenter Resource.

          • Type: String

          The ID for the job or deployment

          name
          • DescriptionThe name assigned for this CloudCenter ResourceValid characters are letters, numbers, underscores, and spaces.

          • Type: String

          The name for the job or deployment

          attributes
          • Description: Identifies attribute details for the deployment entity.
          • Type: Sequence of related information about the resource – these details differ based on the resource being deployed.

        favoriteCreationTime
        • Description: If the job was configured as a favorite job (see Deployments > Favorite Deployments for additional context), then this attribute identifies the time when this configuration took place.
        • Type: Epoch time as a String

Searching

This attribute is only available for v2 APIs. See View Jobs for an example.

  • 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:
        searchValueSearchType Availability
        ideq
        startTimeeq, nu, gtlt
        endTimeeq, nu, nn, gtlt
        totalCosteq, gt, ge, le, gtlt, gtlte, gtelte, gtelt
        favoriteCreationTimeeq, nu, ,nn gtlt
        jobStatusMessageel, eln, fl, fln, fle, nn, emp, noemp
        nodeHourseq, gt, ge, le, gtlt, gtlte, gtelte, gtelt
        nameeq, nn, eln, fle, fln, el, emp, noemp, fl
        descriptioneq, nn, eln, fle, fln, el, emp, noemp, fl
        deploymentEntity.nameeq, nn, eln, fle, fln, el, emp, noemp, fl
        ownerEmailAddresseq
        cloudFamilyeq, nu
        statuseq, 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 APIs?

Both CloudCenter admins and users can use CloudCenter 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 CloudCenter Resource, you receive the HTTP 403 status error mentioned in the HTTP Status Codes section above.

Tenant Admins and Co-Admins

When viewing the responses for user-related APIs, the attributes mentioned in this section help you differentiate the original tenant admin (owner) from a promoted co-admin.

View the type and coAdmin attributes in the View Users API response:

typecoAdminDescription
TenantfalseThis is a tenant admin (owner).
TenanttrueThis is a promoted co-admin.
Icon

Each tenant can only have one tenant admin (owner)  but multiple tenant co-admins. See Promote User to Sub-tenant Owner for additional context.

 

 

  • No labels