Amazon Cloud Map Instances API

openapi: 3.1.0
info:
  title: AWS Cloud Map Instances API
  version: '2017-03-14'
  description: Generated from AWS's published Smithy model for AWS Cloud Map. 5 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://servicediscovery.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /#DeregisterInstance:
    post:
      operationId: DeregisterInstance
      summary: Deregister Instance
      description: Deletes the Amazon Route 53 DNS records and health check, if any, that Cloud Map created for the specified
        instance.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeregisterInstanceResponse'
              example:
                OperationId: 4yejorelbukcjzpnr6tlmrghsjwpngf4-k98rnaiq
        '409':
          description: DuplicateRequest; ResourceInUse
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DuplicateRequest'
        '404':
          description: InstanceNotFound; ServiceNotFound
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InstanceNotFound'
        '400':
          description: InvalidInput
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInput'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Route53AutoNaming_v20170314.DeregisterInstance
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeregisterInstanceRequest'
            example:
              ServiceId: srv-p5zdwlg5uvvzjita
              InstanceId: myservice-53
      tags:
      - Instances
  /#GetInstance:
    post:
      operationId: GetInstance
      summary: Get Instance
      description: Gets information about a specified instance.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetInstanceResponse'
              example:
                ResourceOwner: '123456789012'
                Instance:
                  Id: i-abcd1234
                  Attributes:
                    AWS_INSTANCE_IPV4: 192.0.2.44
                    AWS_INSTANCE_PORT: '80'
                    color: green
                    region: us-west-2
                    stage: beta
                  CreatedByAccount: '123456789012'
        '404':
          description: InstanceNotFound; ServiceNotFound
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InstanceNotFound'
        '400':
          description: InvalidInput
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInput'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Route53AutoNaming_v20170314.GetInstance
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetInstanceRequest'
            example:
              InstanceId: i-abcd1234
              ServiceId: srv-e4anhexample0004
      tags:
      - Instances
  /#ListInstances:
    post:
      operationId: ListInstances
      summary: List Instances
      description: Lists summary information about the instances that you registered by using a specified service.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListInstancesResponse'
              example:
                Instances:
                - Attributes:
                    AWS_INSTANCE_IPV4: 172.2.1.3
                    AWS_INSTANCE_PORT: '808'
                  Id: i-06bdabbae60f65a4e
        '400':
          description: InvalidInput
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInput'
        '404':
          description: ServiceNotFound
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceNotFound'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Route53AutoNaming_v20170314.ListInstances
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListInstancesRequest'
            example:
              ServiceId: srv-qzpwvt2tfqcegapy
      tags:
      - Instances
  /#RegisterInstance:
    post:
      operationId: RegisterInstance
      summary: Register Instance
      description: 'Creates or updates one or more records and, optionally, creates a health check based on the settings in
        a specified service. When you submit a RegisterInstance request, the following occurs: For each DNS record that you
        define in the service that''s specified by ServiceId, a record is created or updated in the hosted zone that''s associated
        with the corresponding namespace. If the service includes HealthCheckConfig, a health check is created based on the
        settings in the health check configuration. The health check, if any, is associated with each of the new or updated
        records. One RegisterInstance request must complete before you can submit another request and specify the same service
        ID and instance ID. For more information, see CreateService. When Cloud Map receives a DNS query for the specified
        DNS name, it returns the applicable value: If the health check is healthy: returns all the records If the health check
        is unhealthy: returns the applicable value for the last healthy instance If you didn''t specify a health check configuration:
        returns all the records For the current quota on the number of instances that you can register using the same namespace
        and using the same service, s'
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/RegisterInstanceResponse'
              example:
                OperationId: 4yejorelbukcjzpnr6tlmrghsjwpngf4-k95yg2u7
        '409':
          description: DuplicateRequest; ResourceInUse
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DuplicateRequest'
        '400':
          description: InvalidInput; ResourceLimitExceeded
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInput'
        '404':
          description: ServiceNotFound
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ServiceNotFound'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Route53AutoNaming_v20170314.RegisterInstance
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/RegisterInstanceRequest'
            example:
              ServiceId: srv-p5zdwlg5uvvzjita
              InstanceId: myservice-53
              Attributes:
                AWS_INSTANCE_IPV4: 172.2.1.3
                AWS_INSTANCE_PORT: '808'
              CreatorRequestId: 7a48a98a-72e6-4849-bfa7-1a458e030d7b
      tags:
      - Instances
  /#DiscoverInstances:
    post:
      operationId: DiscoverInstances
      summary: Discover Instances
      description: Discovers registered instances for a specified namespace and service. You can use DiscoverInstances to
        discover instances for any type of namespace. DiscoverInstances returns a randomized list of instances allowing customers
        to distribute traffic evenly across instances. For public and private DNS namespaces, you can also use DNS queries
        to discover instances.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DiscoverInstancesResponse'
              example:
                Instances:
                - InstanceId: i-abcd1234xmpl5678
                  NamespaceName: example-shared-namespace
                  ServiceName: shared-service
                  HealthStatus: HEALTHY
                  Attributes:
                    AWS_INSTANCE_IPV4: 192.0.2.44
                    AWS_INSTANCE_PORT: '80'
                - InstanceId: i-efgh5678xmpl9012
                  NamespaceName: example-shared-namespace
                  ServiceName: shared-service
                  HealthStatus: HEALTHY
                  Attributes:
                    AWS_INSTANCE_IPV4: 192.0.2.45
                    AWS_INSTANCE_PORT: '80'
        '400':
          description: InvalidInput
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInput'
        '404':
          description: NamespaceNotFound; ServiceNotFound
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/NamespaceNotFound'
        '429':
          description: RequestLimitExceeded
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/RequestLimitExceeded'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Route53AutoNaming_v20170314.DiscoverInstances
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DiscoverInstancesRequest'
            example:
              NamespaceName: example-shared-namespace
              ServiceName: shared-namespace-service
              OwnerAccount: '123456789012'
      tags:
      - Instances
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: servicediscovery
  schemas:
    DeregisterInstanceRequest:
      type: object
      properties:
        ServiceId:
          type: string
          description: The ID or Amazon Resource Name (ARN) of the service that the instance is associated with. If the namespace
            associated with the service is shared with your account, specify the service ARN. For more information about shared
            namespaces, see Cross-account Cloud Map namespace sharing in the Cloud Map Developer Guide.
        InstanceId:
          type: string
          description: The value that you specified for Id in the RegisterInstance request.
      required:
      - ServiceId
      - InstanceId
    DeregisterInstanceResponse:
      type: object
      properties:
        OperationId:
          type: string
          description: A value that you can use to determine whether the request completed successfully. To get the status
            of the operation, see GetOperation.
    DiscoverInstancesRequest:
      type: object
      properties:
        NamespaceName:
          type: string
          description: The HttpName name of the namespace. The HttpName is found in the HttpProperties member of the Properties
            member of the namespace. In most cases, Name and HttpName match. However, if you reuse Name for namespace creation,
            a generated hash is added to HttpName to distinguish the two.
        ServiceName:
          type: string
          description: The name of the service that you specified when you registered the instance.
        MaxResults:
          type: integer
          description: The maximum number of instances that you want Cloud Map to return in the response to a DiscoverInstances
            request. If you don't specify a value for MaxResults, Cloud Map returns up to 100 instances.
        QueryParameters:
          type: object
          additionalProperties:
            type: string
          description: Filters to scope the results based on custom attributes for the instance (for example, {version=v1,
            az=1a}). Only instances that match all the specified key-value pairs are returned.
        OptionalParameters:
          type: object
          additionalProperties:
            type: string
          description: Opportunistic filters to scope the results based on custom attributes. If there are instances that
            match both the filters specified in both the QueryParameters parameter and this parameter, all of these instances
            are returned. Otherwise, the filters are ignored, and only instances that match the filters that are specified
            in the QueryParameters parameter are returned.
        HealthStatus:
          type: string
          enum:
          - HEALTHY
          - UNHEALTHY
          - ALL
          - HEALTHY_OR_ELSE_ALL
          description: The health status of the instances that you want to discover. This parameter is ignored for services
            that don't have a health check configured, and all instances are returned. HEALTHY Returns healthy instances.
            UNHEALTHY Returns unhealthy instances. ALL Returns all instances. HEALTHY_OR_ELSE_ALL Returns healthy instances,
            unless none are reporting a healthy state. In that case, return all instances. This is also called failing open.
        OwnerAccount:
          type: string
          description: The ID of the Amazon Web Services account that owns the namespace associated with the instance, as
            specified in the namespace ResourceOwner field. For instances associated with namespaces that are shared with
            your account, you must specify an OwnerAccount.
      required:
      - NamespaceName
      - ServiceName
    DiscoverInstancesResponse:
      type: object
      properties:
        Instances:
          type: array
          items:
            $ref: '#/components/schemas/HttpInstanceSummary'
          description: A complex type that contains one HttpInstanceSummary for each registered instance.
        InstancesRevision:
          type: integer
          description: The increasing revision associated to the response Instances list. If a new instance is registered
            or deregistered, the InstancesRevision updates. The health status updates don't update InstancesRevision.
    DuplicateRequest:
      type: object
      properties:
        Message:
          type: string
        DuplicateOperationId:
          type: string
          description: The ID of the operation that's already in progress.
    GetInstanceRequest:
      type: object
      properties:
        ServiceId:
          type: string
          description: The ID or Amazon Resource Name (ARN) of the service that the instance is associated with. For services
            created in a shared namespace, specify the service ARN. For more information about shared namespaces, see Cross-account
            Cloud Map namespace sharing in the Cloud Map Developer Guide.
        InstanceId:
          type: string
          description: The ID of the instance that you want to get information about.
      required:
      - ServiceId
      - InstanceId
    GetInstanceResponse:
      type: object
      properties:
        ResourceOwner:
          type: string
          description: The ID of the Amazon Web Services account that created the namespace that contains the service that
            the instance is associated with. If this isn't your account ID, it's the ID of the account that shared the namespace
            with your account.
        Instance:
          $ref: '#/components/schemas/Instance'
    HttpInstanceSummary:
      type: object
      properties:
        InstanceId:
          type: string
          description: The ID of an instance that matches the values that you specified in the request.
        NamespaceName:
          type: string
          description: The HttpName name of the namespace. It's found in the HttpProperties member of the Properties member
            of the namespace.
        ServiceName:
          type: string
          description: The name of the service that you specified when you registered the instance.
        HealthStatus:
          type: string
          enum:
          - HEALTHY
          - UNHEALTHY
          - UNKNOWN
          description: If you configured health checking in the service, the current health status of the service instance.
        Attributes:
          type: object
          additionalProperties:
            type: string
          description: If you included any attributes when you registered the instance, the values of those attributes.
    Instance:
      type: object
      properties:
        Id:
          type: string
          description: 'An identifier that you want to associate with the instance. Note the following: If the service that''s
            specified by ServiceId includes settings for an SRV record, the value of InstanceId is automatically included
            as part of the value for the SRV record. For more information, see DnsRecord > Type. You can use this value to
            update an existing instance. To register a new instance, you must specify a value that''s unique among instances
            that you register by using the same service. If you specify an existing InstanceId and ServiceId, Cloud Map updates
            the existing DNS records. If there''s also an exis'
        CreatorRequestId:
          type: string
          description: A unique string that identifies the request and that allows failed RegisterInstance requests to be
            retried without the risk of executing the operation twice. You must use a unique CreatorRequestId string every
            time you submit a RegisterInstance request if you're registering additional instances for the same namespace and
            service. CreatorRequestId can be any unique string (for example, a date/time stamp).
        Attributes:
          type: object
          additionalProperties:
            type: string
          description: 'A string map that contains the following information for the service that you specify in ServiceId:
            The attributes that apply to the records that are defined in the service. For each attribute, the applicable value.
            Do not include sensitive information in the attributes if the namespace is discoverable by public DNS queries.
            Supported attribute keys include the following: AWS_ALIAS_DNS_NAME If you want Cloud Map to create a Route 53
            alias record that routes traffic to an Elastic Load Balancing load balancer, specify the DNS name that''s associated
            with the load balancer. For information about h'
        CreatedByAccount:
          type: string
          description: The ID of the Amazon Web Services account that registered the instance. If this isn't your account
            ID, it's the ID of the account that shared the namespace with your account or the ID of another account with which
            the namespace has been shared. For more information about shared namespaces, see Cross-account Cloud Map namespace
            sharing in the Cloud Map Developer Guide.
      required:
      - Id
    InstanceNotFound:
      type: object
      properties:
        Message:
          type: string
    InstanceSummary:
      type: object
      properties:
        Id:
          type: string
          description: The ID for an instance that you created by using a specified service.
        Attributes:
          type: object
          additionalProperties:
            type: string
          description: 'A string map that contains the following information: The attributes that are associated with the
            instance. For each attribute, the applicable value. Supported attribute keys include the following: AWS_ALIAS_DNS_NAME
            For an alias record that routes traffic to an Elastic Load Balancing load balancer, the DNS name that''s associated
            with the load balancer. AWS_EC2_INSTANCE_ID (HTTP namespaces only) The Amazon EC2 instance ID for the instance.
            When the AWS_EC2_INSTANCE_ID attribute is specified, then the AWS_INSTANCE_IPV4 attribute contains the primary
            private IPv4 address. AWS_INIT_HEALTH_STATUS '
        CreatedByAccount:
          type: string
          description: The ID of the Amazon Web Services account that registered the instance. If this isn't your account
            ID, it's the ID of the account that shared the namespace with your account or the ID of another account with which
            the namespace has been shared. For more information about shared namespaces, see Cross-account Cloud Map namespace
            sharing in the Cloud Map Developer Guide.
    InvalidInput:
      type: object
      properties:
        Message:
          type: string
    ListInstancesRequest:
      type: object
      properties:
        ServiceId:
          type: string
          description: The ID or Amazon Resource Name (ARN) of the service that you want to list instances for. For services
            created in a shared namespace, specify the service ARN. For more information about shared namespaces, see Cross-account
            Cloud Map namespace sharing in the Cloud Map Developer Guide.
        NextToken:
          type: string
          description: For the first ListInstances request, omit this value. If more than MaxResults instances match the specified
            criteria, you can submit another ListInstances request to get the next group of results. Specify the value of
            NextToken from the previous response in the next request.
        MaxResults:
          type: integer
          description: The maximum number of instances that you want Cloud Map to return in the response to a ListInstances
            request. If you don't specify a value for MaxResults, Cloud Map returns up to 100 instances.
      required:
      - ServiceId
    ListInstancesResponse:
      type: object
      properties:
        ResourceOwner:
          type: string
          description: The ID of the Amazon Web Services account that created the namespace that contains the specified service.
            If this isn't your account ID, it's the ID of the account that shared the namespace with your account.
        Instances:
          type: array
          items:
            $ref: '#/components/schemas/InstanceSummary'
          description: Summary information about the instances that are associated with the specified service.
        NextToken:
          type: string
          description: If more than MaxResults instances match the specified criteria, you can submit another ListInstances
            request to get the next group of results. Specify the value of NextToken from the previous response in the next
            request.
    NamespaceNotFound:
      type: object
      properties:
        Message:
          type: string
    RegisterInstanceRequest:
      type: object
      properties:
        ServiceId:
          type: string
          description: The ID or Amazon Resource Name (ARN) of the service that you want to use for settings for the instance.
            For services created in a shared namespace, specify the service ARN. For more information about shared namespaces,
            see Cross-account Cloud Map namespace sharing in the Cloud Map Developer Guide.
        InstanceId:
          type: string
          description: 'An identifier that you want to associate with the instance. Note the following: If the service that''s
            specified by ServiceId includes settings for an SRV record, the value of InstanceId is automatically included
            as part of the value for the SRV record. For more information, see DnsRecord > Type. You can use this value to
            update an existing instance. To register a new instance, you must specify a value that''s unique among instances
            that you register by using the same service. If you specify an existing InstanceId and ServiceId, Cloud Map updates
            the existing DNS records, if any. If there''s also'
        CreatorRequestId:
          type: string
          description: A unique string that identifies the request and that allows failed RegisterInstance requests to be
            retried without the risk of executing the operation twice. You must use a unique CreatorRequestId string every
            time you submit a RegisterInstance request if you're registering additional instances for the same namespace and
            service. CreatorRequestId can be any unique string (for example, a date/time stamp).
        Attributes:
          type: object
          additionalProperties:
            type: string
          description: 'A string map that contains the following information for the service that you specify in ServiceId:
            The attributes that apply to the records that are defined in the service. For each attribute, the applicable value.
            Do not include sensitive information in the attributes if the namespace is discoverable by public DNS queries.
            The following are the supported attribute keys. AWS_ALIAS_DNS_NAME If you want Cloud Map to create an Amazon Route
            53 alias record that routes traffic to an Elastic Load Balancing load balancer, specify the DNS name that''s associated
            with the load balancer. For information'
      required:
      - ServiceId
      - InstanceId
      - Attributes
    RegisterInstanceResponse:
      type: object
      properties:
        OperationId:
          type: string
          description: A value that you can use to determine whether the request completed successfully. To get the status
            of the operation, see GetOperation.
    RequestLimitExceeded:
      type: object
      properties:
        Message:
          type: string
    ServiceNotFound:
      type: object
      properties:
        Message:
          type: string
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/servicediscovery/service/2017-03-14/servicediscovery-2017-03-14.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)