APIs.io Engineering Platform API Versions API

openapi: 3.0.0
info:
  version: "1.0.0"
  x-release: v4
  title: APIs.io Engineering Platform Amazon API Gateway 2014 11 13 API Versions API
  description: <fullname>Amazon API Gateway</fullname> <p>Amazon API Gateway helps developers deliver robust, secure, and scalable mobile and web application back ends. API Gateway allows developers to securely connect mobile and web applications to APIs that run on AWS Lambda, Amazon EC2, or other publicly addressable web services that are hosted outside of AWS.</p>
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png
    backgroundColor: '#FFFFFF'
  termsOfService: https://aws.amazon.com/service-terms/
  contact:
    name: Mike Ralphson
    email: mike.ralphson@gmail.com
    url: https://github.com/mermade/aws2openapi
    x-twitter: PermittedSoc
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/
  x-providerName: amazonaws.com
  x-serviceName: apigateway
  x-origin:
  - contentType: application/json
    url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/apigateway-2015-07-09.normal.json
    converter:
      url: https://github.com/mermade/aws2openapi
    x-apisguru-driver: external
  x-apiClientRegistration:
    url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
  x-apisguru-categories:
  - cloud
  x-preferred: true
servers:
- url: http://apigateway.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Amazon API Gateway multi-region endpoint
- url: https://apigateway.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The Amazon API Gateway multi-region endpoint
- url: http://apigateway.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
- url: https://apigateway.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
security:
- hmac: []
tags:
- name: API Versions
  description: The **API Versions** endpoints enable you to manage your [API's versions](https://learning.postman.com/docs/designing-and-developing-your-api/versioning-an-api/versioning-an-api-overview/#publishing-an-api-version). Only users with the [API Admin](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#api-roles) or [Workspace Admin](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#workspace-roles) role can publish and manage versions.
paths:
  /apis/{apiId}/versions:
    parameters:
    - $ref: '#/components/parameters/apiId'
    - $ref: '#/components/parameters/v10Accept'
    get:
      summary: APIs.io Engineering Platform Get all versions
      description: Gets all the published versions of an API.
      operationId: getApiVersions
      tags:
      - API Versions
      responses:
        '200':
          $ref: '#/components/responses/getApiVersions'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/apiVersions404Response'
        '422':
          $ref: '#/components/responses/v9Unsupported'
        '500':
          $ref: '#/components/responses/common500Error'
      parameters:
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/limit'
    post:
      summary: APIs.io Engineering Platform Create a version
      description: 'Creates a new API version asynchronously and immediately returns an HTTP `202 Accepted` response. The response contains a polling link to the task status API in the `Location` header.


        This endpoint is equivalent to publishing a version in Postman app, which is the snapshot of API collections and schema at a given point in time.

        '
      operationId: createApiVersion
      tags:
      - API Versions
      requestBody:
        $ref: '#/components/requestBodies/createApiVersion'
      responses:
        '202':
          $ref: '#/components/responses/createApiVersion'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/apiSchema403ErrorForbidden'
                - $ref: '#/components/schemas/featureUnavailable403Error'
              examples:
                Forbidden:
                  $ref: '#/components/examples/apiSchema403ErrorForbidden'
                Feature Unavailable:
                  $ref: '#/components/examples/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/apiVersions404Response'
        '422':
          $ref: '#/components/responses/apiVersion422ErrorStateInconsistent'
        '500':
          $ref: '#/components/responses/common500Error'
  /apis/{apiId}/versions/{versionId}:
    parameters:
    - $ref: '#/components/parameters/apiId'
    - $ref: '#/components/parameters/apiVersionId'
    - $ref: '#/components/parameters/v10Accept'
    put:
      summary: APIs.io Engineering Platform Update a version
      description: 'Updates an API version.


        **Note:**


        This endpoint returns an HTTP `404 Not Found` response when an API version is pending publication.

        '
      operationId: updateApiVersion
      tags:
      - API Versions
      requestBody:
        $ref: '#/components/requestBodies/updateApiVersion'
      responses:
        '200':
          $ref: '#/components/responses/updateApiVersion'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/api403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/apiVersion404ErrorNotFound'
        '500':
          $ref: '#/components/responses/common500Error'
    delete:
      summary: APIs.io Engineering Platform Delete a version
      description: 'Deletes an API version. On success, this returns an HTTP `204 No Content` response.


        **Note:**


        This endpoint returns an HTTP `404 Not Found` response when an API version is pending publication.

        '
      operationId: deleteApiVersion
      tags:
      - API Versions
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/apiVersion400ErrorInstanceNotFound'
                - $ref: '#/components/schemas/v10HeaderMissing'
              examples:
                API Version Not Found:
                  $ref: '#/components/examples/apiVersion400ErrorInstanceNotFound'
                Missing v10 Accept Header:
                  $ref: '#/components/examples/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/api403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/apiVersion404ErrorNotFound'
        '500':
          $ref: '#/components/responses/common500Error'
components:
  examples:
    v10HeaderMissing:
      value:
        name: instanceNotFoundError
        message: API not found. For v10 and later APIs, ensure that your request sends the "application/vnd.api.v10+json" Accept header.
    apiVersion404ErrorNotFound:
      value:
        type: VersionNotFound
        title: API Version not found.
        details: We could not find the API Version you are looking for.
    featureUnavailable403Error:
      value:
        type: https://api.postman.com/problems/forbidden
        title: Forbidden
        detail: This feature isn't available in your region.
        status: 403
    apiVersion400ErrorInstanceNotFound:
      value:
        error:
          name: instanceNotFoundError
          message: We could not find the API version you are looking for
    api404ErrorNotFound:
      value:
        type: instanceNotFoundError
        title: We could not find the API you are looking for
        detail: We could not find the API you are looking for.
    api403ErrorForbidden:
      value:
        title: You are not permitted to perform the action.
        detail: Please ensure that you have required permissions
        type: ForbiddenError
    apiSchema403ErrorForbidden:
      value:
        title: You are not permitted to perform the action.
        detail: You do not have access to perform this operation.
        type: ForbiddenError
  responses:
    featureUnavailable403Error:
      description: Feature Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/featureUnavailable403Error'
          example:
            value:
              type: https://api.postman.com/problems/forbidden
              title: Forbidden
              detail: This feature isn't available in your region.
              status: 403
    createApiVersion:
      description: Accepted
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: The version's ID.
                example: 12ece9e1-2abf-4edc-8e34-de66e74114d2
              createdAt:
                type: string
                format: date-time
                description: The date and time at which the version was created.
                example: '2023-06-09T14:48:45.000Z'
              updatedAt:
                type: string
                format: date-time
                description: The date and time at which the version was last updated.
                example: '2023-06-09T19:50:49.000Z'
              name:
                type: string
                description: The version's name.
                example: v1
              releaseNotes:
                type: string
                description: Information about the API version release. For example, changelog notes.
                example: This is the first release.
          example:
            createdAt: '2023-06-09T14:48:45.000Z'
            updatedAt: '2023-06-09T19:50:49.000Z'
            id: 12ece9e1-2abf-4edc-8e34-de66e74114d2
            name: v1
            releaseNotes: This is the first release.
      headers:
        Location:
          $ref: '#/components/headers/Location'
    apiVersions404Response:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/api404ErrorNotFound'
          examples:
            API Not Found:
              $ref: '#/components/examples/api404ErrorNotFound'
    getApiVersions:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            description: Information about the API's versions.
            properties:
              meta:
                type: object
                description: The response's meta information for paginated results.
                properties:
                  limit:
                    type: integer
                    description: The maximum number of records in the paginated response.
                    example: 100
                  total:
                    type: integer
                    description: The number of records that match the defined criteria.
                    example: 1000
                  nextCursor:
                    type: string
                    format: base64
                    description: The pagination cursor that points to the next record in the results set.
                    example: VGh1IE1hciAxNiAyMDIzIDE3OjIxOjUzIEdNVCswMDAwIChDb29yZGluYXRlZCBVbml2ZXJzYWwgVGltZSk=
              versions:
                type: array
                items:
                  type: object
                  title: API Version Data Schema
                  description: Information about the API version.
                  properties:
                    id:
                      type: string
                      description: The version's ID.
                      example: 12ece9e1-2abf-4edc-8e34-de66e74114d2
                    name:
                      type: string
                      description: The version's name.
                      example: Release 1.0
                    createdAt:
                      type: string
                      format: date-time
                      description: The date and time at which the version was created.
                      example: '2023-06-09T14:48:45.000Z'
                    updatedAt:
                      type: string
                      format: date-time
                      description: The date and time at which the version was last updated.
                      example: '2023-06-09T14:48:45.000Z'
                    releaseNotes:
                      type: string
                      description: The version's release notes.
                      example: This is the first release.
          example:
            versions:
            - createdAt: '2022-06-09T14:48:45.000Z'
              updatedAt: '2022-06-09T19:50:49.000Z'
              id: 07d940bf-40fc-4acd-a11e-be6769894af0
              name: Release 2.0
              releaseNotes: This is the second release of the Test API.
            - createdAt: '2022-06-09T14:48:45.000Z'
              updatedAt: '2022-06-09T19:50:49.000Z'
              id: 3563baaa-07a2-46ed-9fd2-0e8a3c5f7ec2
              name: Release 1.0
              releaseNotes: This is the first release of the Test API. For more information, read the documentation.
            meta:
              nextCursor: VGh1IE1hciAxNiAyMDIzIDE3OjIxOjUzIEdNVCswMDAwIChDb29yZGluYXRlZCBVbml2ZXJzYWwgVGltZSk=
              limit: 2
              total: 1000
    api401ErrorUnauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/unauthorized
              title:
                type: string
                description: A short summary of the problem.
                example: Unauthorized
              detail:
                type: string
                description: Information about the error.
                example: An API key must be provided in the request header or query string
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 401
              instance:
                type: string
                description: The URI reference that identifies the specific occurrence of the problem.
                example: /collections/12ece9e1-2abf-4edc-8e34-de66e74114d2/requests/%7B%7BrequestId%7D%7D
          example:
            type: https://api.postman.com/problems/unauthorized
            title: Unauthorized
            detail: An API key must be provided in the request header or query string
            status: 401
            instance: /collections/12ece9e1-2abf-4edc-8e34-de66e74114d2/requests/%7B%7BrequestId%7D%7D
    common500Error:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/internal-server-error
              title:
                type: string
                description: A short summary of the problem.
                example: Internal Server Error
              detail:
                type: string
                description: Information about the error.
                example: Internal Server Error
          example:
            type: https://api.postman.com/problems/internal-server-error
            title: Internal Server Error
            detail: Internal Server Error
    updateApiVersion:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: The version's ID.
                example: 8d7ba74e-2c36-4e36-a263-f3c0c9ae21d2
              name:
                type: string
                description: The version's name.
                example: Release 1.5
              createdAt:
                type: string
                format: date-time
                description: The date and time at which the version was created.
                example: '2022-06-09T14:48:45.000Z'
              updatedAt:
                type: string
                format: date-time
                description: The date and time at which the version was last updated.
                example: '2022-06-09T19:50:49.000Z'
              releaseNotes:
                type: string
                description: The version's release notes.
                example: This is the first public release update.
          example:
            createdAt: '2022-06-09T14:48:45.000Z'
            updatedAt: '2022-06-09T19:50:49.000Z'
            id: 8d7ba74e-2c36-4e36-a263-f3c0c9ae21d2
            name: Release 1.5
            releaseNotes: This is the first public release update.
    v10HeaderMissing:
      description: Missing v10 Accept Header
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/v10HeaderMissing'
          examples:
            Missing v10 Accept Header:
              $ref: '#/components/examples/v10HeaderMissing'
    apiVersion422ErrorStateInconsistent:
      description: API State Inconsistent
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                description: The error type.
                example: APIStateInconsistent
              title:
                type: string
                description: A short summary of the problem.
                example: API state seems to be inconsistent.
              detail:
                type: string
                description: Details about the error.
                example: Please perform a Git push from the Postman app to sync state between app and repository.
          example:
            type: APIStateInconsistent
            title: API state seems to be inconsistent.
            detail: Please perform a Git push from the Postman app to sync state between app and repository.
    api403ErrorAndFeatureUnavailable:
      description: Forbidden
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/api403ErrorForbidden'
            - $ref: '#/components/schemas/featureUnavailable403Error'
          examples:
            Forbidden:
              $ref: '#/components/examples/api403ErrorForbidden'
            Feature Unavailable:
              $ref: '#/components/examples/featureUnavailable403Error'
    v9Unsupported:
      description: v9 Unsupported
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                description: The error type.
                example: unsupportedEntityError
              title:
                type: string
                description: A short summary of the problem.
                example: Unsupported API
              detail:
                type: string
                description: Details about the error.
                example: This endpoint does not support v9 APIs.
          example:
            type: unsupportedEntityError
            title: Unsupported API
            detail: This endpoint does not support v9 APIs.
    apiVersion404ErrorNotFound:
      description: API Version Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/apiVersion404ErrorNotFound'
          examples:
            API Version Not Found:
              $ref: '#/components/examples/apiVersion404ErrorNotFound'
  schemas:
    apiVersion404ErrorNotFound:
      title: API Version Not Found
      type: object
      properties:
        type:
          type: string
          description: The type of error.
          example: VersionNotFound
        title:
          type: string
          description: A short summary of the problem.
          example: API Version not found.
        detail:
          type: string
          description: Information about the error.
          example: We could not find the API Version you are looking for.
    v10HeaderMissing:
      title: Missing v10 Accept Header
      type: object
      properties:
        name:
          type: string
          description: The error name.
          example: instanceNotFoundError
        message:
          type: string
          description: The error message.
          example: API not found. For v10 and later APIs, ensure that your request sends the "application/vnd.api.v10+json" Accept header.
    apiVersionId:
      type: string
      example: 12ece9e1-2abf-4edc-8e34-de66e74114d2
    api404ErrorNotFound:
      title: API Not Found
      type: object
      properties:
        type:
          type: string
          description: The type of error.
          example: instanceNotFoundError
        title:
          type: string
          description: A short summary of the problem.
          example: We could not find the API you are looking for
        detail:
          type: string
          description: Information about the error.
          example: We could not find the API you are looking for
    featureUnavailable403Error:
      title: Feature Unavailable
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
          example: https://api.postman.com/problems/forbidden
        title:
          type: string
          description: A short summary of the problem.
          example: Forbidden
        detail:
          type: string
          description: Information about the error.
          example: This feature isn't available in your region.
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 403
    limit:
      type: integer
      default: 10
      example: 10
    apiSchema403ErrorForbidden:
      title: Forbidden
      type: object
      properties:
        type:
          type: string
          description: The type of error.
          example: ForbiddenError
        title:
          type: string
          description: A short summary of the problem.
          example: You are not permitted to perform the action.
        detail:
          type: string
          description: Information about the error.
          example: You do not have access to perform this operation.
    cursor:
      type: string
      example: RnJpIEZlYiAyNCAyMDIzIDEzOjI0OjA5IEdNVCswMDAwIChDb29yZGluYXRlZCBVbml2ZXJzYWwgVGltZSk=
    api403ErrorForbidden:
      title: Forbidden
      type: object
      properties:
        type:
          type: string
          description: The type of error.
          example: ForbiddenError
        title:
          type: string
          description: A short summary of the problem.
          example: You are not permitted to perform the action.
        detail:
          type: string
          description: Information about the error.
          example: Please ensure that you have required permissions
    apiVersion400ErrorInstanceNotFound:
      title: API Version Not Found
      type: object
      properties:
        error:
          type: object
          properties:
            name:
              type: string
              description: The type of error.
              example: instanceNotFoundError
            message:
              type: string
              description: The error message.
              example: We could not find the API version you are looking for
  requestBodies:
    updateApiVersion:
      content:
        application/json:
          schema:
            type: object
            description: Information about the API version.
            required:
            - name
            properties:
              name:
                type: string
                description: The version's name.
                example: Release 1.5
              releaseNotes:
                type: string
                description: The version's Markdown-supported release notes.
                example: This is the first public release update.
          example:
            name: Release 1.5
            releaseNotes: This is the first public release update.
    createApiVersion:
      content:
        application/json:
          schema:
            anyOf:
            - type: object
              title: Create Version Schema (Not Git-Linked)
              description: Information about the API version.
              required:
              - name
              - schemas
              - collections
              properties:
                name:
                  type: string
                  description: The version's name.
                  example: v1
                schemas:
                  type: array
                  description: A list of the version's schemas.
                  items:
                    type: object
                    description: Information about the schema.
                    properties:
                      id:
                        type: string
                        description: The schema's ID.
                        example: 5381f010-c4c1-11ed-afa1-0242ac120002
                collections:
                  type: array
                  description: A list of the version's collections.
                  items:
                    type: object
                    description: Information about the collection.
                    properties:
                      id:
                        type: string
                        description: The collection's ID.
                        example: 123456-12ece9e1-2abf-4edc-8e34-de66e74114d2
                releaseNotes:
                  type: string
                  description: Information about the API version release. For example, changelog notes.
                  example: This is the first release.
            - type: object
              title: Create Version Schema (Git-Linked with root File)
              description: Information about the API version.
              required:
              - name
              - branch
              - schemas
              - collections
              properties:
                name:
                  type: string
                  description: The version's name.
                  example: v1
                branch:
                  type: string
                  description: The branch ID.
                  example: develop
                schemas:
                  type: array
                  description: A list of the version's schemas.
                  items:
                    type: object
                    description: Information about the schema.
                    properties:
                      filePath:
                        type: string
                        description: The path to the schema root file in the Git repository.
                        example: index.yaml
                collections:
                  type: array
                  description: A list of the version's collections.
                  items:
                    type: object
                    description: Information about the collection.
                    properties:
                      filePath:
                        type: string
                        description: Path to a collection in the Git repository.
                        example: postman/collection/c1.json
                releaseNotes:
                  type: string
                  description: Information about the API version release. For example, changelog notes.
                  example: This is the first release.
            - type: object
              title: Create Version Schema (Git-Linked)
              description: Information about the API version.
              required:
              - name
              - branch
              - schemas
              - collections
              properties:
                name:
                  type: string
                  description: The version's name.
                  example: v1
                branch:
                  type: string
                  description: The branch ID.
                  example: main
                schemas:
                  type: array
                  description: A list of the version's schemas.
                  items:
                    type: object
                    description: Information about the schema.
                    properties:
                      directoryPath:
                        type: string
                        description: The path to the root directory where schemas are stored in the Git repository.
                        example: postman/schemas
                collections:
                  type: array
                  description: A list of the version's collections.
                  items:
                    type: object
                    description: Information about the collection.
                    properties:
                      filePath:
                        type: string
                        description: The path to the collection in the Git repository.
                        example: postman/collection/c1.json
                releaseNotes:
                  type: string
                  example: This is the first release.
                  description: Information about the API version release. For example, changelog notes.
          examples:
            Create Version:
              value:
                name: v1
                releaseNotes: This is the first release.
                collections:
                - id: e8a015e0-f472-4bb3-a523-57ce7c4583ed
                schemas:
                - id: 18a015e0-f472-4bb3-a523-57ce7c458387
            Git-Linked Version with Schema Directory Path:
              value:
                name: v1
                branch: develop
                releaseNotes: This is the first release.
                collections:
                - filePath: postman/collections/c1.js

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apis-io-engineering-platform/refs/heads/main/openapi/engineering-platform-api-versions-api-openapi.yml