Amazon API Gateway V1 (REST)

openapi: 3.1.0
info:
  title: Amazon API Gateway V1 (REST)
  description: >-
    The API Gateway V1 control plane API is used to create, deploy,
    and manage REST APIs in Amazon API Gateway.
  version: '2015-07-09'
  contact:
    name: AWS Support
    url: https://aws.amazon.com/premiumsupport/
  termsOfService: https://aws.amazon.com/service-terms/
externalDocs:
  description: Amazon API Gateway V1 API Reference
  url: https://docs.aws.amazon.com/apigateway/latest/api/Welcome.html
servers:
- url: https://apigateway.{region}.amazonaws.com
  description: Amazon API Gateway regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
tags:
- name: ApiKeys
  description: Manage API keys
- name: Deployments
  description: Manage API deployments
- name: Methods
  description: Manage HTTP methods on resources
- name: Resources
  description: Manage resources within a REST API
- name: RestApis
  description: Manage REST API definitions
- name: Stages
  description: Manage deployment stages
- name: UsagePlans
  description: Manage usage plans
security:
- sigv4: []
paths:
  /restapis:
    get:
      operationId: getRestApis
      summary: Amazon API Gateway List REST APIs
      description: >-
        Lists the RestApi resources for the caller's account.
      tags:
      - RestApis
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApis'
              examples:
                getRestApis200Example:
                  summary: Default getRestApis 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - example-value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createRestApi
      summary: Amazon API Gateway Create a REST API
      description: >-
        Creates a new RestApi resource.
      tags:
      - RestApis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRestApiRequest'
            examples:
              createRestApiRequestExample:
                summary: Default createRestApi request
                x-microcks-default: true
                value:
                  name: my-resource
                  description: A description of this resource.
                  version: '1.0'
                  endpointConfiguration:
                    types:
                    - EDGE
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApi'
              examples:
                createRestApi201Example:
                  summary: Default createRestApi 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: my-resource
                    description: A description of this resource.
                    createdDate: '2025-03-15T14:30:00Z'
                    version: '1.0'
                    endpointConfiguration:
                      types:
                      - EDGE
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /restapis/{restapi_id}:
    parameters:
    - $ref: '#/components/parameters/RestApiId'
    get:
      operationId: getRestApi
      summary: Amazon API Gateway Get a REST API
      description: Retrieves a single RestApi resource.
      tags:
      - RestApis
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApi'
              examples:
                getRestApi200Example:
                  summary: Default getRestApi 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: my-resource
                    description: A description of this resource.
                    createdDate: '2025-03-15T14:30:00Z'
                    version: '1.0'
                    endpointConfiguration:
                      types:
                      - EDGE
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRestApi
      summary: Amazon API Gateway Delete a REST API
      description: Deletes the specified RestApi resource.
      tags:
      - RestApis
      responses:
        '202':
          description: Accepted
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /restapis/{restapi_id}/resources:
    parameters:
    - $ref: '#/components/parameters/RestApiId'
    get:
      operationId: getResources
      summary: Amazon API Gateway List Resources
      description: Lists the Resource resources for a RestApi.
      tags:
      - Resources
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resources'
              examples:
                getResources200Example:
                  summary: Default getResources 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /restapis/{restapi_id}/resources/{resource_id}/methods/{http_method}:
    parameters:
    - $ref: '#/components/parameters/RestApiId'
    - $ref: '#/components/parameters/ResourceId'
    - $ref: '#/components/parameters/HttpMethod'
    get:
      operationId: getMethod
      summary: Amazon API Gateway Get a Method
      description: Retrieves the Method resource for a given HTTP verb on a Resource.
      tags:
      - Methods
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Method'
              examples:
                getMethod200Example:
                  summary: Default getMethod 200 response
                  x-microcks-default: true
                  value:
                    httpMethod: example-value
                    authorizationType: example-value
                    apiKeyRequired: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: putMethod
      summary: Amazon API Gateway Put a Method
      description: Adds an HTTP method to a Resource.
      tags:
      - Methods
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutMethodRequest'
            examples:
              putMethodRequestExample:
                summary: Default putMethod request
                x-microcks-default: true
                value:
                  authorizationType: example-value
                  apiKeyRequired: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Method'
              examples:
                putMethod201Example:
                  summary: Default putMethod 201 response
                  x-microcks-default: true
                  value:
                    httpMethod: example-value
                    authorizationType: example-value
                    apiKeyRequired: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMethod
      summary: Amazon API Gateway Delete a Method
      description: Deletes a Method resource.
      tags:
      - Methods
      responses:
        '202':
          description: Accepted
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /restapis/{restapi_id}/deployments:
    parameters:
    - $ref: '#/components/parameters/RestApiId'
    get:
      operationId: getDeployments
      summary: Amazon API Gateway List Deployments
      description: Lists deployments for a RestApi.
      tags:
      - Deployments
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployments'
              examples:
                getDeployments200Example:
                  summary: Default getDeployments 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createDeployment
      summary: Amazon API Gateway Create a Deployment
      description: Creates a deployment for a RestApi.
      tags:
      - Deployments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
            examples:
              createDeploymentRequestExample:
                summary: Default createDeployment request
                x-microcks-default: true
                value:
                  stageName: my-resource
                  description: A description of this resource.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
              examples:
                createDeployment201Example:
                  summary: Default createDeployment 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    description: A description of this resource.
                    createdDate: '2025-03-15T14:30:00Z'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /restapis/{restapi_id}/stages:
    parameters:
    - $ref: '#/components/parameters/RestApiId'
    get:
      operationId: getStages
      summary: Amazon API Gateway List Stages
      description: Lists deployment stages for a RestApi.
      tags:
      - Stages
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stages'
              examples:
                getStages200Example:
                  summary: Default getStages 200 response
                  x-microcks-default: true
                  value:
                    item:
                    - example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /apikeys:
    get:
      operationId: getApiKeys
      summary: Amazon API Gateway List API Keys
      description: Lists the ApiKeys for the caller's account.
      tags:
      - ApiKeys
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeys'
              examples:
                getApiKeys200Example:
                  summary: Default getApiKeys 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createApiKey
      summary: Amazon API Gateway Create an API Key
      description: Creates a new ApiKey resource.
      tags:
      - ApiKeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
            examples:
              createApiKeyRequestExample:
                summary: Default createApiKey request
                x-microcks-default: true
                value:
                  name: my-resource
                  description: A description of this resource.
                  enabled: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
              examples:
                createApiKey201Example:
                  summary: Default createApiKey 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    value: example-value
                    name: my-resource
                    enabled: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /usageplans:
    get:
      operationId: getUsagePlans
      summary: Amazon API Gateway List Usage Plans
      description: Lists the usage plans for the caller's account.
      tags:
      - UsagePlans
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagePlans'
              examples:
                getUsagePlans200Example:
                  summary: Default getUsagePlans 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createUsagePlan
      summary: Amazon API Gateway Create a Usage Plan
      description: Creates a usage plan with throttle and quota configuration.
      tags:
      - UsagePlans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUsagePlanRequest'
            examples:
              createUsagePlanRequestExample:
                summary: Default createUsagePlan request
                x-microcks-default: true
                value:
                  name: my-resource
                  description: A description of this resource.
                  throttle:
                    burstLimit: 86
                    rateLimit: 27.41
                  quota:
                    limit: 68
                    period: DAY
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagePlan'
              examples:
                createUsagePlan201Example:
                  summary: Default createUsagePlan 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: my-resource
                    throttle:
                      burstLimit: 7
                      rateLimit: 67.04
                    quota:
                      limit: 17
                      period: DAY
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4 signed request.
  parameters:
    RestApiId:
      name: restapi_id
      in: path
      required: true
      description: Identifier of the RestApi resource.
      schema:
        type: string
    ResourceId:
      name: resource_id
      in: path
      required: true
      description: Identifier of the Resource.
      schema:
        type: string
    HttpMethod:
      name: http_method
      in: path
      required: true
      description: HTTP verb of the Method.
      schema:
        type: string
        enum: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, ANY]
  responses:
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The request was not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    RestApi:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the RestApi.
          example: abc123
        name:
          type: string
          description: Name of the RestApi.
          example: my-resource
        description:
          type: string
          description: Description of the RestApi.
          example: A description of this resource.
        createdDate:
          type: string
          format: date-time
          description: Timestamp when the RestApi was created.
          example: '2025-03-15T14:30:00Z'
        version:
          type: string
          description: Version identifier of the API.
          example: '1.0'
        endpointConfiguration:
          $ref: '#/components/schemas/EndpointConfiguration'
    RestApis:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RestApi'
          example:
          - example-value
    CreateRestApiRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name of the new RestApi.
          example: my-resource
        description:
          type: string
          description: Optional description.
          example: A description of this resource.
        version:
          type: string
          description: Version identifier.
          example: '1.0'
        endpointConfiguration:
          $ref: '#/components/schemas/EndpointConfiguration'
    EndpointConfiguration:
      type: object
      properties:
        types:
          type: array
          description: List of endpoint types (EDGE, REGIONAL, PRIVATE).
          items:
            type: string
            enum: [EDGE, REGIONAL, PRIVATE]
          example:
          - EDGE
    Resource:
      type: object
      properties:
        id:
          type: string
          description: Resource identifier.
          example: abc123
        parentId:
          type: string
          description: Parent resource identifier.
          example: abc123
        pathPart:
          type: string
          description: Last path segment for this resource.
          example: example-value
        path:
          type: string
          description: Full path of the resource.
          example: example-value
    Resources:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
          example:
          - example-value
    Method:
      type: object
      properties:
        httpMethod:
          type: string
          description: HTTP method verb.
          example: example-value
        authorizationType:
          type: string
          description: Authorization type for invoking the method.
          example: example-value
        apiKeyRequired:
          type: boolean
          description: Whether the method requires an API key.
          example: true
    PutMethodRequest:
      type: object
      required: [authorizationType]
      properties:
        authorizationType:
          type: string
          description: Authorization type (NONE, AWS_IAM, CUSTOM, COGNITO_USER_POOLS).
          example: example-value
        apiKeyRequired:
          type: boolean
          description: Whether to require an API key.
          example: true
    Deployment:
      type: object
      properties:
        id:
          type: string
          description: Deployment identifier.
          example: abc123
        description:
          type: string
          description: Description of the deployment.
          example: A description of this resource.
        createdDate:
          type: string
          format: date-time
          description: Timestamp when the deployment was created.
          example: '2025-03-15T14:30:00Z'
    Deployments:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Deployment'
          example:
          - example-value
    CreateDeploymentRequest:
      type: object
      required: [stageName]
      properties:
        stageName:
          type: string
          description: Name of the stage to deploy to.
          example: my-resource
        description:
          type: string
          description: Description of the deployment.
          example: A description of this resource.
    Stage:
      type: object
      properties:
        deploymentId:
          type: string
          description: Identifier of the deployment.
          example: abc123
        stageName:
          type: string
          description: Name of the stage.
          example: my-resource
        description:
          type: string
          description: Description of the stage.
          example: A description of this resource.
    Stages:
      type: object
      properties:
        item:
          type: array
          items:
            $ref: '#/components/schemas/Stage'
          example:
          - example-value
    ApiKey:
      type: object
      properties:
        id:
          type: string
          description: ApiKey identifier.
          example: abc123
        value:
          type: string
          description: Value of the ApiKey.
          example: example-value
        name:
          type: string
          description: Name of the ApiKey.
          example: my-resource
        enabled:
          type: boolean
          description: Whether the ApiKey is enabled.
          example: true
    ApiKeys:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ApiKey'
          example:
          - example-value
    CreateApiKeyRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the ApiKey.
          example: my-resource
        description:
          type: string
          description: Description of the ApiKey.
          example: A description of this resource.
        enabled:
          type: boolean
          description: Whether the ApiKey should be enabled.
          example: true
    UsagePlan:
      type: object
      properties:
        id:
          type: string
          description: Usage plan identifier.
          example: abc123
        name:
          type: string
          description: Usage plan name.
          example: my-resource
        throttle:
          $ref: '#/components/schemas/ThrottleSettings'
        quota:
          $ref: '#/components/schemas/QuotaSettings'
    UsagePlans:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UsagePlan'
          example:
          - example-value
    CreateUsagePlanRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name of the usage plan.
          example: my-resource
        description:
          type: string
          description: Description of the usage plan.
          example: A description of this resource.
        throttle:
          $ref: '#/components/schemas/ThrottleSettings'
        quota:
          $ref: '#/components/schemas/QuotaSettings'
    ThrottleSettings:
      type: object
      properties:
        burstLimit:
          type: integer
          description: Burst limit for requests.
          example: 49
        rateLimit:
          type: number
          description: Steady-state rate limit (requests per second).
          example: 69.99
    QuotaSettings:
      type: object
      properties:
        limit:
          type: integer
          description: Maximum number of requests in the period.
          example: 24
        period:
          type: string
          description: Time period (DAY, WEEK, MONTH).
          enum: [DAY, WEEK, MONTH]
          example: DAY
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: example-value
        code:
          type: string
          description: Error code.
          example: example-value