AWS CloudFormation Resources API

openapi: 3.1.0
info:
  title: AWS Cloud Control Change Sets Resources API
  description: AWS Cloud Control API provides a uniform set of five API operations to create, read, update, delete, and list (CRUDL) supported cloud resources. It offers a standardized way to manage AWS and third-party resource types available in the CloudFormation Registry, without needing to learn each individual service API. You specify the resource type and a JSON blob of desired state, and Cloud Control API handles the rest.
  version: '2021-09-30'
  contact:
    name: AWS Support
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-logo:
    url: https://aws.amazon.com/cloudformation/logo.png
servers:
- url: https://cloudcontrolapi.{region}.amazonaws.com
  description: AWS Cloud Control API Regional Endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - eu-west-1
      - eu-west-2
      - eu-central-1
      - ap-southeast-1
      - ap-southeast-2
      - ap-northeast-1
security:
- AWS_Signature_V4: []
tags:
- name: Resources
  description: CRUDL operations for creating, reading, updating, deleting, and listing cloud resources through a uniform interface.
paths:
  /?Action=CreateResource:
    post:
      operationId: createResource
      summary: Create a New Cloud Resource
      description: Creates the specified resource. For more information, see Creating a resource in the CloudFormation User Guide. After you have initiated a resource creation request, you can monitor the progress of your request by calling GetResourceRequestStatus using the RequestToken of the ProgressEvent returned by CreateResource.
      tags:
      - Resources
      parameters:
      - $ref: '#/components/parameters/VersionParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - TypeName
              - DesiredState
              properties:
                TypeName:
                  type: string
                  description: The name of the resource type. Resource type names follow the format of Vendor::Service::Resource (e.g. AWS::EC2::Instance).
                  minLength: 10
                  maxLength: 196
                  pattern: '[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}'
                DesiredState:
                  type: string
                  description: A JSON string representing the desired state of the resource, consisting of the property values for creating the resource.
                  minLength: 1
                  maxLength: 262144
                TypeVersionId:
                  type: string
                  description: For private resource types, the type version to use. If not specified, the default version is used.
                  minLength: 1
                  maxLength: 128
                  pattern: '[A-Za-z0-9-]+'
                RoleArn:
                  type: string
                  description: The Amazon Resource Name (ARN) of the IAM role for Cloud Control API to use when performing this resource operation.
                  minLength: 20
                  maxLength: 2048
                  pattern: arn:.+:iam::[0-9]{12}:role/.+
                ClientToken:
                  type: string
                  description: A unique identifier to ensure the idempotency of the resource request.
                  minLength: 1
                  maxLength: 128
                  pattern: '[-A-Za-z0-9+/=]+'
            examples:
              CreateresourceRequestExample:
                summary: Default createResource request
                x-microcks-default: true
                value:
                  TypeName: example_value
                  DesiredState: example_value
                  TypeVersionId: '500123'
                  RoleArn: example_value
                  ClientToken: example_value
      responses:
        '200':
          description: Resource creation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ProgressEvent:
                    $ref: '#/components/schemas/ProgressEvent'
              examples:
                Createresource200Example:
                  summary: Default createResource 200 response
                  x-microcks-default: true
                  value:
                    ProgressEvent:
                      TypeName: example_value
                      Identifier: example_value
                      RequestToken: example_value
                      HooksRequestToken: example_value
                      Operation: CREATE
                      OperationStatus: PENDING
                      EventTime: 42.5
                      ResourceModel: example_value
                      StatusMessage: example_value
                      ErrorCode: NotUpdatable
                      RetryAfter: 42.5
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/TypeNotFoundError'
        '409':
          $ref: '#/components/responses/AlreadyExistsError'
        '429':
          $ref: '#/components/responses/ThrottlingError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=GetResource:
    post:
      operationId: getResource
      summary: Read a Cloud Resource
      description: Returns information about the current state of the specified resource. For details, see Reading a resource's current state in the CloudFormation User Guide.
      tags:
      - Resources
      parameters:
      - $ref: '#/components/parameters/VersionParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - TypeName
              - Identifier
              properties:
                TypeName:
                  type: string
                  description: The name of the resource type.
                  minLength: 10
                  maxLength: 196
                  pattern: '[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}'
                Identifier:
                  type: string
                  description: The identifier for the resource. You can specify the primary identifier, or any secondary identifier defined for the resource type in its resource schema.
                  minLength: 1
                  maxLength: 1024
                TypeVersionId:
                  type: string
                  description: For private resource types, the type version to use.
                  minLength: 1
                  maxLength: 128
                  pattern: '[A-Za-z0-9-]+'
                RoleArn:
                  type: string
                  description: IAM role ARN for Cloud Control API to assume.
                  minLength: 20
                  maxLength: 2048
                  pattern: arn:.+:iam::[0-9]{12}:role/.+
            examples:
              GetresourceRequestExample:
                summary: Default getResource request
                x-microcks-default: true
                value:
                  TypeName: example_value
                  Identifier: example_value
                  TypeVersionId: '500123'
                  RoleArn: example_value
      responses:
        '200':
          description: Resource details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  TypeName:
                    type: string
                    description: The name of the resource type.
                  ResourceDescription:
                    $ref: '#/components/schemas/ResourceDescription'
              examples:
                Getresource200Example:
                  summary: Default getResource 200 response
                  x-microcks-default: true
                  value:
                    TypeName: example_value
                    ResourceDescription:
                      Identifier: example_value
                      Properties: example_value
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '429':
          $ref: '#/components/responses/ThrottlingError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=UpdateResource:
    post:
      operationId: updateResource
      summary: Update an Existing Cloud Resource
      description: Updates the specified property values of the resource. You specify your resource property updates as a JSON patch document. After you have initiated a resource update request, you can monitor the progress by calling GetResourceRequestStatus using the RequestToken of the ProgressEvent returned by UpdateResource.
      tags:
      - Resources
      parameters:
      - $ref: '#/components/parameters/VersionParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - TypeName
              - Identifier
              - PatchDocument
              properties:
                TypeName:
                  type: string
                  description: The name of the resource type.
                  minLength: 10
                  maxLength: 196
                  pattern: '[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}'
                Identifier:
                  type: string
                  description: The identifier for the resource to update.
                  minLength: 1
                  maxLength: 1024
                PatchDocument:
                  type: string
                  description: A JavaScript Object Notation (JSON) document listing the patch operations that represent the updates to apply to the current resource properties. Uses the RFC 6902 JSON Patch format.
                  minLength: 1
                  maxLength: 262144
                TypeVersionId:
                  type: string
                  description: For private resource types, the type version to use.
                  minLength: 1
                  maxLength: 128
                  pattern: '[A-Za-z0-9-]+'
                RoleArn:
                  type: string
                  description: IAM role ARN for Cloud Control API to assume.
                  minLength: 20
                  maxLength: 2048
                  pattern: arn:.+:iam::[0-9]{12}:role/.+
                ClientToken:
                  type: string
                  description: A unique identifier to ensure idempotency.
                  minLength: 1
                  maxLength: 128
                  pattern: '[-A-Za-z0-9+/=]+'
            examples:
              UpdateresourceRequestExample:
                summary: Default updateResource request
                x-microcks-default: true
                value:
                  TypeName: example_value
                  Identifier: example_value
                  PatchDocument: example_value
                  TypeVersionId: '500123'
                  RoleArn: example_value
                  ClientToken: example_value
      responses:
        '200':
          description: Resource update initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ProgressEvent:
                    $ref: '#/components/schemas/ProgressEvent'
              examples:
                Updateresource200Example:
                  summary: Default updateResource 200 response
                  x-microcks-default: true
                  value:
                    ProgressEvent:
                      TypeName: example_value
                      Identifier: example_value
                      RequestToken: example_value
                      HooksRequestToken: example_value
                      Operation: CREATE
                      OperationStatus: PENDING
                      EventTime: 42.5
                      ResourceModel: example_value
                      StatusMessage: example_value
                      ErrorCode: NotUpdatable
                      RetryAfter: 42.5
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/ThrottlingError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=DeleteResource:
    post:
      operationId: deleteResource
      summary: Delete a Cloud Resource
      description: Deletes the specified resource. After you have initiated a resource deletion request, you can monitor the progress by calling GetResourceRequestStatus using the RequestToken of the ProgressEvent returned by DeleteResource.
      tags:
      - Resources
      parameters:
      - $ref: '#/components/parameters/VersionParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - TypeName
              - Identifier
              properties:
                TypeName:
                  type: string
                  description: The name of the resource type.
                  minLength: 10
                  maxLength: 196
                  pattern: '[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}'
                Identifier:
                  type: string
                  description: The identifier for the resource to delete.
                  minLength: 1
                  maxLength: 1024
                TypeVersionId:
                  type: string
                  description: For private resource types, the type version to use.
                  minLength: 1
                  maxLength: 128
                  pattern: '[A-Za-z0-9-]+'
                RoleArn:
                  type: string
                  description: IAM role ARN for Cloud Control API to assume.
                  minLength: 20
                  maxLength: 2048
                  pattern: arn:.+:iam::[0-9]{12}:role/.+
                ClientToken:
                  type: string
                  description: A unique identifier to ensure idempotency.
                  minLength: 1
                  maxLength: 128
                  pattern: '[-A-Za-z0-9+/=]+'
            examples:
              DeleteresourceRequestExample:
                summary: Default deleteResource request
                x-microcks-default: true
                value:
                  TypeName: example_value
                  Identifier: example_value
                  TypeVersionId: '500123'
                  RoleArn: example_value
                  ClientToken: example_value
      responses:
        '200':
          description: Resource deletion initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ProgressEvent:
                    $ref: '#/components/schemas/ProgressEvent'
              examples:
                Deleteresource200Example:
                  summary: Default deleteResource 200 response
                  x-microcks-default: true
                  value:
                    ProgressEvent:
                      TypeName: example_value
                      Identifier: example_value
                      RequestToken: example_value
                      HooksRequestToken: example_value
                      Operation: CREATE
                      OperationStatus: PENDING
                      EventTime: 42.5
                      ResourceModel: example_value
                      StatusMessage: example_value
                      ErrorCode: NotUpdatable
                      RetryAfter: 42.5
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/ThrottlingError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=ListResources:
    post:
      operationId: listResources
      summary: List Resources of a Specified Type
      description: Returns information about the specified resources. For more information, see Discovering resources in the CloudFormation User Guide. You can use this operation to discover resources that are available in your account.
      tags:
      - Resources
      parameters:
      - $ref: '#/components/parameters/VersionParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - TypeName
              properties:
                TypeName:
                  type: string
                  description: The name of the resource type to list.
                  minLength: 10
                  maxLength: 196
                  pattern: '[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}'
                TypeVersionId:
                  type: string
                  description: For private resource types, the type version to use.
                  minLength: 1
                  maxLength: 128
                  pattern: '[A-Za-z0-9-]+'
                RoleArn:
                  type: string
                  description: IAM role ARN for Cloud Control API to assume.
                  minLength: 20
                  maxLength: 2048
                  pattern: arn:.+:iam::[0-9]{12}:role/.+
                NextToken:
                  type: string
                  description: If the previous paginated request did not return all available results, the response includes a NextToken.
                  minLength: 1
                  maxLength: 2048
                MaxResults:
                  type: integer
                  description: Maximum number of results per page.
                  minimum: 1
                  maximum: 100
                ResourceModel:
                  type: string
                  description: The resource model to use to select the resources to return. Used for filtering by secondary identifiers.
            examples:
              ListresourcesRequestExample:
                summary: Default listResources request
                x-microcks-default: true
                value:
                  TypeName: example_value
                  TypeVersionId: '500123'
                  RoleArn: example_value
                  NextToken: example_value
                  MaxResults: 10
                  ResourceModel: example_value
      responses:
        '200':
          description: Resource list returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  TypeName:
                    type: string
                  ResourceDescriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResourceDescription'
                  NextToken:
                    type: string
              examples:
                Listresources200Example:
                  summary: Default listResources 200 response
                  x-microcks-default: true
                  value:
                    TypeName: example_value
                    ResourceDescriptions:
                    - Identifier: example_value
                      Properties: example_value
                    NextToken: example_value
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/TypeNotFoundError'
        '429':
          $ref: '#/components/responses/ThrottlingError'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    VersionParam:
      name: Version
      in: query
      required: true
      schema:
        type: string
        default: '2021-09-30'
      description: The API version. Fixed to 2021-09-30.
  responses:
    ResourceNotFoundError:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ThrottlingError:
      description: The request was denied due to request throttling.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: The input fails to satisfy the constraints specified by the service.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: An internal service error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ConflictError:
      description: The resource is currently being modified by another operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AlreadyExistsError:
      description: A resource with the specified identifier already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TypeNotFoundError:
      description: The specified resource type was not found in the CloudFormation Registry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ProgressEvent:
      type: object
      description: Represents the current status of a resource operation request.
      properties:
        TypeName:
          type: string
          description: The resource type name.
          example: example_value
        Identifier:
          type: string
          description: The primary identifier for the resource.
          example: example_value
        RequestToken:
          type: string
          description: The unique token representing this resource operation request. Use this token with GetResourceRequestStatus to check operation progress.
          example: example_value
        HooksRequestToken:
          type: string
          description: The unique token for hooks processing.
          example: example_value
        Operation:
          type: string
          description: The resource operation type.
          enum:
          - CREATE
          - DELETE
          - UPDATE
          example: CREATE
        OperationStatus:
          type: string
          description: The current status of the resource operation request.
          enum:
          - PENDING
          - IN_PROGRESS
          - SUCCESS
          - FAILED
          - CANCEL_IN_PROGRESS
          - CANCEL_COMPLETE
          example: PENDING
        EventTime:
          type: number
          description: When the resource operation request was initiated (Unix timestamp).
          example: 42.5
        ResourceModel:
          type: string
          description: A JSON string representing the resource model.
          example: example_value
        StatusMessage:
          type: string
          description: A message explaining the current status.
          example: example_value
        ErrorCode:
          type: string
          description: The error code if the operation failed.
          enum:
          - NotUpdatable
          - InvalidRequest
          - AccessDenied
          - InvalidCredentials
          - AlreadyExists
          - NotFound
          - ResourceConflict
          - Throttling
          - ServiceLimitExceeded
          - NotStabilized
          - GeneralServiceException
          - ServiceInternalError
          - NetworkFailure
          - InternalFailure
          - InvalidTypeConfiguration
          - HandlerInternalFailure
          - NonCompliant
          - Unknown
          - UnsupportedTarget
          example: NotUpdatable
        RetryAfter:
          type: number
          description: When to retry the operation (Unix timestamp).
          example: 42.5
    ResourceDescription:
      type: object
      description: Represents information about a provisioned resource.
      properties:
        Identifier:
          type: string
          description: The primary identifier for the resource.
          example: example_value
        Properties:
          type: string
          description: A JSON string representing the current resource property values. The properties returned depend on the resource type schema.
          example: example_value
    ErrorResponse:
      type: object
      properties:
        Message:
          type: string
          description: The error message.
          example: example_value
        Code:
          type: string
          description: The error code.
          example: example_value
  securitySchemes:
    AWS_Signature_V4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication.