openapi: 3.1.0
info:
  title: Bango Alias API
  version: 1.0.{build_number}
  contact:
    name: Bango Support
    url: https://developer.bango.com
    email: support@bango.com
  description: |
    **This document is written for BANGO INTERNAL users. It's not suitable for external publication** (but may be useful as a starting point for it)

    The Bango Alias API allows authenticated/authorized users to create and manage mappings from one type of identifier to another, where both identifiers conceptually refer to the same resource. The alias is typically (but not necessarily) a partner-specific ID, mapping to a Bango-owned ID.
    For convenience and performance, private endpoints were also implemented for all endpoints that can be authenticated in order to avoid authentication being necessary in calls between internal services.

    ## Change log
    - [ENG-5695](https://bangonet.atlassian.net/browse/ENG-5695)
      - Added specification for the private and public endpoints
    - [ENG-5229](https://bangonet.atlassian.net/browse/ENG-5229)
      - Added POST endpoint to retrieve alias and alias by target
    - 2023-09-25
      - Remove get-by-rid and most list filters
      - Remove the rid from the returned resource
    - 2023-09-07
      - Clarify that the alias and target string length limits are bytes not UTF-8 characters
    - 2023-08-21
      - Change constraints on `alias` and `target` params in create requests, permitting custom target types and values
      - Limit the list operation to a single filter parameter, and change the parameter constraints
    - 1.0.3 - 2023-08-07
      - Add 404 for "create" operation, for wrong nsid
    - 1.0.2
      - Simplify `sort` parameter
      - Clarify desired implementation order
    - 1.0.0
      - First draft
servers:
  - url: https://api.bango.com
    description: Production server
tags:
  - name: env-production-public
    description: Currently deployed to production environment
  - name: env-production-private
    description: Currently deployed to production environment
paths:
  /ns/{nsid}/aliases:
    post:
      tags:
        - env-production-public
      operationId: alias-authenticated-create [env-production-public]
      summary: Create an alias resource
      description: |
        Use this endpoint to create an alias resource.

        **This endpoint should be used whenever external entities need to access it, and therefore need to be authenticated.**

        The response includes the alias resource plus a unique `rid` that refers to the alias resource.

        - With this API, use the `rid` or the `alias` value to retrieve the alias resource later.
        - With other Bango APIs that support aliases, you can use the `alias` value instead of the `target` value

        400 response error codes:
          - `invalid-json` if the request body isn't valid JSON format
          - `missing-parameter` for any mandatory parameter missing from the request body
          - `invalid-parameter` for any parameter that's syntactically or semantically incorrect. For example:
            - If this specification defines a parameter as a string, and an array of strings is supplied
            - If this specification defines a parameter as a datetime, and an invalid datetime is supplied
            - If parameters should be in a particular order (eg chronological datetimes) and they aren't
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
      requestBody:
        description: |
          Data needed to create an alias.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alias:
                  $ref: '#/components/schemas/alias-string'
                target:
                  $ref: '#/components/schemas/target-string'
              required:
                - alias
                - target
            example:
              alias: my-special-id:adrfhaerhu2
              target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
      responses:
        '201':
          description: |
            Resource created.
          content:
            application/vnd.bango.alias.v1+json:
              schema:
                $ref: '#/components/schemas/alias'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
    get:
      tags:
        - env-production-public
      operationId: alias-authenticated-list [env-production-public]
      summary: Retrieve alias resources matching a target
      description: |
        Use this endpoint to fetch alias resources matching a target.

        **This endpoint should be used whenever external entities need to access it, and therefore need to be authenticated.**

        Use the `target` query parameter to specify the target. The response includes all alias resources with that target, in the API consumer's namespace only. If no alias resources match the target, the response is HTTP 200 with an empty array.

        Example: `target=payment-instrument-token%3Ad2ba0aeb-491a-4014-b920-cfdd264b9c64` (where `%3A` is a URL-encoded `:` character)

        It is an error if the filter parameter is not specified.

        ### Error responses

        400 response error codes:
          - `missing-parameter`
            - If the `target` query parameter is not specified

        404 is returned ONLY if the authenticated user has no rights to access the `nsid`.
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
        - in: query
          name: target
          description: |
            Match alias resources where the `target` value exactly matches the parameter.
          example: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
          schema:
            $ref: '#/components/schemas/target-string'
      responses:
        '200':
          description: |
            Zero or more resources found
          content:
            application/vnd.bango.aliases.v1+json:
              schema:
                description: Array of zero or more alias resources
                type: array
                items:
                  $ref: '#/components/schemas/alias'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
  /ns/{nsid}/aliases/{alias}:
    get:
      tags:
        - env-production-public
      operationId: alias-authenticated-get [env-production-public]
      summary: Retrieve an alias resource
      description: |
        Use this endpoint to retrieve an alias resource.

        **This endpoint should be used whenever external entities need to access it, and therefore need to be authenticated.**

        You identify an alias resource using its `alias`. For example, if an alias resource looks like this:

        ```json
        {
          "lastUpdate": "2023-05-10T10:33:54Z",
          "alias": "my-special-id:adrfhaerhu2",
          "target": "payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607"
        }
        ```

        Then this request returns the resource:

        - `GET https://{server}/ns/{nsid}/aliases/my-special-id:adrfhaerhu2`

        **This behavior applies to the Bango Alias API only**. In other Bango APIs where aliases are supported, an alias in a request maps to the `target` from the resource. In the Bango Alias API only, using `alias` lets you easily access the alias resource.
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
        - in: path
          name: alias
          required: true
          schema:
            $ref: '#/components/schemas/alias-string'
      responses:
        '200':
          description: Resource found
          content:
            application/vnd.bango.alias.v1+json:
              schema:
                $ref: '#/components/schemas/alias'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
  /ns/{nsid}/aliases/actions:
    post:
      tags:
        - env-production-public
      operationId: alias-authenticated-retrieve [env-production-public]
      summary: Retrieve an alias resource
      description: |
        Use this endpoint to retrieve an alias resource.

        **This endpoint should be used whenever external entities need to access it, and therefore need to be authenticated.**

        You identify an alias resource using its `alias`. For example, if an alias resource looks like this:

        ```json
        {
          "lastUpdate": "2023-05-10T10:33:54Z",
          "alias": "my-special-id:adrfhaerhu2",
          "target": "payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607"
        }
        ```

        400 response error codes:
          - `invalid-json` if the request body isn't valid JSON format
          - `missing-parameter` for any mandatory parameter missing from the request body
          - `invalid-parameter` for any parameter that's syntactically or semantically incorrect. For example:
            - If this specification defines a parameter as a string, and an array of strings is supplied
            - If this specification defines a parameter as a datetime, and an invalid datetime is supplied
            - If parameters should be in a particular order (eg chronological datetimes) and they aren't
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
      requestBody:
        description: |
          Data needed to retrieve an alias. A request specifies an action `type` and any action-specific data (the `payload`).

          Available action types:
           - [`GET_ALIAS`](/schemas/GET_ALIAS): Get an alias
           - [`GET_ALIAS_BY_TARGET`](/schemas/GET_ALIAS_BY_TARGET): Get an alias by target
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/GET_ALIAS'
                - $ref: '#/components/schemas/GET_ALIAS_BY_TARGET'
            examples:
              GET_ALIAS:
                value:
                  type: GET_ALIAS
                  payload:
                    alias: my-special-id:adrfhaerhu2
              GET_ALIAS_BY_TARGET:
                value:
                  type: GET_ALIAS_BY_TARGET
                  payload:
                    target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
      responses:
        '200':
          description: |
            Resource retrieved.
          content:
            application/vnd.bango.alias.v1+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/alias'
                  - $ref: '#/components/schemas/aliases'
              examples:
                GET_ALIAS response:
                  value:
                    lastUpdate: '2022-12-21T08:59:32Z'
                    alias: my-special-id:adrfhaerhu2
                    target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
                GET_ALIAS_BY_TARGET response:
                  value:
                    - lastUpdate: '2022-12-21T08:59:32Z'
                      alias: my-special-id:adrfhaerhu2
                      target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
                    - lastUpdate: '2022-12-22T08:59:32Z'
                      alias: my-special-id:adrfhaerhu3
                      target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
  /private/ns/{nsid}/aliases:
    post:
      tags:
        - env-production-private
      operationId: alias-private-create [env-production-private]
      summary: Create an alias resource - private
      description: |
        Use this endpoint to create an alias resource.

        **This endpoint should be used between internal services to bypass the authentication avoiding unnecessary overhead**

        The response includes the alias resource plus a unique `rid` that refers to the alias resource.

        - With this API, use the `rid` or the `alias` value to retrieve the alias resource later.
        - With other Bango APIs that support aliases, you can use the `alias` value instead of the `target` value

        400 response error codes:
          - `invalid-json` if the request body isn't valid JSON format
          - `missing-parameter` for any mandatory parameter missing from the request body
          - `invalid-parameter` for any parameter that's syntactically or semantically incorrect. For example:
            - If this specification defines a parameter as a string, and an array of strings is supplied
            - If this specification defines a parameter as a datetime, and an invalid datetime is supplied
            - If parameters should be in a particular order (eg chronological datetimes) and they aren't
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
      requestBody:
        description: |
          Data needed to create an alias.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alias:
                  $ref: '#/components/schemas/alias-string'
                target:
                  $ref: '#/components/schemas/target-string'
              required:
                - alias
                - target
            example:
              alias: my-special-id:adrfhaerhu2
              target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
      responses:
        '201':
          description: |
            Resource created.
          content:
            application/vnd.bango.alias.v1+json:
              schema:
                $ref: '#/components/schemas/alias'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
    get:
      tags:
        - env-production-private
      operationId: alias-private-list [env-production-private]
      summary: Retrieve alias resources matching a target - private
      description: |
        Use this endpoint to fetch alias resources matching a target.

        **This endpoint should be used between internal services to bypass the authentication avoiding unnecessary overhead**

        Use the `target` query parameter to specify the target. The response includes all alias resources with that target, in the API consumer's namespace only. If no alias resources match the target, the response is HTTP 200 with an empty array.

        Example: `target=payment-instrument-token%3Ad2ba0aeb-491a-4014-b920-cfdd264b9c64` (where `%3A` is a URL-encoded `:` character)

        It is an error if the filter parameter is not specified.

        ### Error responses

        400 response error codes:
          - `missing-parameter`
            - If the `target` query parameter is not specified

        404 is returned ONLY if the authenticated user has no rights to access the `nsid`.
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
        - in: query
          name: target
          description: |
            Match alias resources where the `target` value exactly matches the parameter.
          example: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
          schema:
            $ref: '#/components/schemas/target-string'
      responses:
        '200':
          description: |
            Zero or more resources found
          content:
            application/vnd.bango.aliases.v1+json:
              schema:
                description: Array of zero or more alias resources
                type: array
                items:
                  $ref: '#/components/schemas/alias'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
  /private/ns/{nsid}/aliases/{alias}:
    get:
      tags:
        - env-production-private
      operationId: alias-private-get [env-production-private]
      summary: Retrieve an alias resource - private
      description: |
        Use this endpoint to retrieve an alias resource.

        **This endpoint should be used between internal services to bypass the authentication avoiding unnecessary overhead**

        You identify an alias resource using its `alias`. For example, if an alias resource looks like this:

        ```json
        {
          "lastUpdate": "2023-05-10T10:33:54Z",
          "alias": "my-special-id:adrfhaerhu2",
          "target": "payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607"
        }
        ```

        Then this request returns the resource:

        - `GET https://{server}/ns/{nsid}/aliases/my-special-id:adrfhaerhu2`

        **This behavior applies to the Bango Alias API only**. In other Bango APIs where aliases are supported, an alias in a request maps to the `target` from the resource. In the Bango Alias API only, using `alias` lets you easily access the alias resource.
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
        - in: path
          name: alias
          required: true
          schema:
            $ref: '#/components/schemas/alias-string'
      responses:
        '200':
          description: Resource found
          content:
            application/vnd.bango.alias.v1+json:
              schema:
                $ref: '#/components/schemas/alias'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
  /private/ns/{nsid}/aliases/actions:
    post:
      tags:
        - env-production-private
      operationId: alias-private-retrieve [env-production-private]
      summary: Retrieve an alias resource - private
      description: |
        Use this endpoint to retrieve an alias resource.

        **This endpoint should be used between internal services to bypass the authentication avoiding unnecessary overhead**

        You identify an alias resource using its `alias`. For example, if an alias resource looks like this:

        ```json
        {
          "lastUpdate": "2023-05-10T10:33:54Z",
          "alias": "my-special-id:adrfhaerhu2",
          "target": "payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607"
        }
        ```

        400 response error codes:
          - `invalid-json` if the request body isn't valid JSON format
          - `missing-parameter` for any mandatory parameter missing from the request body
          - `invalid-parameter` for any parameter that's syntactically or semantically incorrect. For example:
            - If this specification defines a parameter as a string, and an array of strings is supplied
            - If this specification defines a parameter as a datetime, and an invalid datetime is supplied
            - If parameters should be in a particular order (eg chronological datetimes) and they aren't
      parameters:
        - $ref: '#/components/parameters/NamespaceId'
      requestBody:
        description: |
          Data needed to retrieve an alias. A request specifies an action `type` and any action-specific data (the `payload`).

          Available action types:
           - [`GET_ALIAS`](/schemas/GET_ALIAS): Get an alias
           - [`GET_ALIAS_BY_TARGET`](/schemas/GET_ALIAS_BY_TARGET): Get an alias by target
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/GET_ALIAS'
                - $ref: '#/components/schemas/GET_ALIAS_BY_TARGET'
            examples:
              GET_ALIAS:
                value:
                  type: GET_ALIAS
                  payload:
                    alias: my-special-id:adrfhaerhu2
              GET_ALIAS_BY_TARGET:
                value:
                  type: GET_ALIAS_BY_TARGET
                  payload:
                    target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
      responses:
        '200':
          description: |
            Resource retrieved.
          content:
            application/vnd.bango.alias.v1+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/alias'
                  - $ref: '#/components/schemas/aliases'
              examples:
                GET_ALIAS response:
                  value:
                    lastUpdate: '2022-12-21T08:59:32Z'
                    alias: my-special-id:adrfhaerhu2
                    target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
                GET_ALIAS_BY_TARGET response:
                  value:
                    - lastUpdate: '2022-12-21T08:59:32Z'
                      alias: my-special-id:adrfhaerhu2
                      target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
                    - lastUpdate: '2022-12-22T08:59:32Z'
                      alias: my-special-id:adrfhaerhu3
                      target: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/InvalidCredentialsErrorResponse'
        '403':
          $ref: '#/components/responses/PermissionDeniedErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
components:
  schemas:
    namespace-id:
      title: Namespace ID
      description: |
        Globally unique namespace ID. These IDs are opaque, not guessable, and not sequential.

        Bango provides each Bango partner with a unique set of resource URIs. All resource URI paths start with `/ns/{nsid}`, where `{nsid}` is the namespace ID. No other Bango partner shares this namespace. Partner credentials permit access only to URIs with this namespace.
      type: string
      format: uuid
      example: 673c74de-ce5b-4f79-9851-2544d1d836cb
    target-string:
      title: Target string
      description: |
        A string to which an alternative identifier (alias) maps.

        A target always has two parts, in this order, separated by a colon:

        - A type
        - A value appropriate to that type

        For example, `payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607`.

        A type may contain only alphanumeric characters and `-` characters, and must not be empty. IDs may be any non-empty string. The maximum length of a target string, including type and value, is 1000 bytes (encoded as UTF-8).
      type: string
      pattern: ^[-a-zA-Z0-9]+:.+$
      maxLength: 1000
      example: payment-instrument-token:2ad5968f-f36b-475c-8296-31fc27efb607
    alias-string:
      title: Alias string
      description: |
        A string that acts as an alternative identifier for another string.

        An alias always has two parts, in this order, separated by a colon:

        - A type
        - A unique ID corresponding to that type

        For example, `my-special-id:adrfhaerhu2`.

        A type may contain only alphanumeric characters and `-` characters, and must not be empty. IDs may be any non-empty string. The maximum length of an alias string, including type and ID, is 1000 bytes (encoded as UTF-8).

        For each partner namespace, the alias must be unique. For example, one namespace can contain aliases `abc:123` and `xyz:123`, but can't contain two aliases both called `abc:123` even if they correspond to different Bango-owned IDs. It's OK for two different namespaces each to contain an alias `abc:123`.
      type: string
      pattern: ^[-a-zA-Z0-9]+:.+$
      maxLength: 1000
      example: my-special-id:adrfhaerhu2
    alias:
      title: Alias resource
      description: |
        An alias resource, representing a mapping from one type of identifier (the _alias_) to another (the _target_), where both identifiers conceptually refer to the same resource. The alias is typically (but not necessarily) a partner-specific value, mapping to a Bango-owned value.

        Every alias maps to exactly one target. A target may have multiple aliases.
      type: object
      properties:
        lastUpdate:
          type: string
          format: date-time
          description: |
            RFC 3339 datetime of the last update to this resource
          example: '2022-12-21T08:59:32Z'
        alias:
          $ref: '#/components/schemas/alias-string'
        target:
          $ref: '#/components/schemas/target-string'
    CommonErrorResponse:
      type: object
      required:
        - errors
    invalid-json:
      title: invalid-json
      description: The request body is not valid JSON
      type: object
      properties:
        code:
          const: invalid-json
        meta:
          description: Additional information to help identify the specific error case (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The request body is not valid JSON
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/invalid-json
      required:
        - code
        - meta
        - message
    missing-parameter:
      title: missing-parameter
      description: A required parameter is missing from the request
      type: object
      properties:
        code:
          const: missing-parameter
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            param:
              description: The name of the missing parameter
              type: string
          required:
            - param
        message:
          description: Human-readable message describing the error
          type: string
          example: A required parameter was missing from the request
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/missing-parameter
      required:
        - code
        - meta
        - message
    invalid-parameter:
      title: invalid-parameter
      description: A request parameter is invalid
      type: object
      properties:
        code:
          const: invalid-parameter
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            param:
              description: The name of the invalid parameter
              type: string
            reason:
              description: Optional human-readable information to explain why the parameter is invalid. Code must not rely on the content of this string.
              type: string
              example: 'Expected format: YYYY-MM-DD'
          required:
            - param
        message:
          description: Human-readable message describing the error
          type: string
          example: A parameter in the request was not valid
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/invalid-parameter
      required:
        - code
        - meta
        - message
    BadRequest:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/invalid-json'
                  - $ref: '#/components/schemas/missing-parameter'
                  - $ref: '#/components/schemas/invalid-parameter'
    invalid-credentials:
      title: invalid-credentials
      description: Authentication error - invalid credentials
      type: object
      properties:
        code:
          const: invalid-credentials
        meta:
          description: Additional information to help identify the specific error case (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The supplied credentials are not valid
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/invalid-credentials
      required:
        - code
        - meta
        - message
    InvalidCredentials:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/invalid-credentials'
    permission-denied:
      title: permission-denied
      description: Authorization error - permission denied
      type: object
      properties:
        code:
          const: permission-denied
        meta:
          description: Additional information to help identify the specific error case (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The client is not permitted to perform this operation
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/permission-denied
      required:
        - code
        - meta
        - message
    PermissionDenied:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/permission-denied'
    not-found:
      title: not-found
      description: Not found or access denied
      type: object
      properties:
        code:
          const: not-found
        meta:
          description: Additional information to help identify the specific error case (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The requested resource was not found
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/not-found
      required:
        - code
        - meta
        - message
    NotFound:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/not-found'
    too-many-requests:
      title: too-many-requests
      description: Too many requests
      type: object
      properties:
        code:
          const: too-many-requests
        meta:
          description: Additional information to help identify the specific error case (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: Request limit reached. Please try again later
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/too-many-requests
      required:
        - code
        - meta
        - message
    TooManyRequests:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/too-many-requests'
    internal-server-error:
      title: internal-server-error
      description: Internal server error
      type: object
      properties:
        code:
          const: internal-server-error
        meta:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the request can be retried
              type: boolean
              default: true
        message:
          description: Human-readable message describing the error
          type: string
          example: The server encountered an unexpected condition which prevented it from fulfilling the request
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/internal-server-error
      required:
        - code
        - meta
        - message
    InternalServerError:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/internal-server-error'
    service-unavailable:
      title: service-unavailable
      description: Service is unavailable
      type: object
      properties:
        code:
          const: service-unavailable
        meta:
          description: Additional information to help identify the specific error case (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The service is undergoing maintenance and is not available. Please try again later
        url:
          description: URL to more information about the error type
          type: string
          format: url
          example: https://developer.bango.com/error-codes/service-unavailable
      required:
        - code
        - meta
        - message
    ServiceUnavailable:
      allOf:
        - $ref: '#/components/schemas/CommonErrorResponse'
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/service-unavailable'
    GET_ALIAS:
      title: GET_ALIAS
      description: |
        Retrieve an alias resource.

        ### Supported HTTP responses

        - HTTP 200 OK:
          - [`ALIAS`](/schemas/alias) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
            - the request body is not valid JSON
          - `code` == `missing-parameter`:
            - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
            - a parameter is not of the expected type, or
            - a parameter violates the documented constraints
        - HTTP 404 Not Found:
            - `code` == `not found`:
              - the requested resource is not found
      type: object
      properties:
        type:
          const: GET_ALIAS
        payload:
          type: object
          properties:
            alias:
              $ref: '#/components/schemas/alias-string'
          required:
            - alias
      required:
        - type
        - payload
    GET_ALIAS_BY_TARGET:
      title: GET_ALIAS_BY_TARGET
      description: |
        Retrieve alias resources matching a target.

        - HTTP 200 OK:
          - [`ALIASES`](/schemas/aliases) response action
        - HTTP 400 BAD REQUEST with one or more errors:
          - `code` == `invalid-json`:
               - the request body is not valid JSON
          - `code` == `missing-parameter`:
               - a required parameter is omitted from the request action
          - `code` == `invalid-parameter`:
               - a parameter is not of the expected type, or
               - a parameter violates the documented constraints
      type: object
      properties:
        type:
          const: GET_ALIAS_BY_TARGET
        payload:
          type: object
          properties:
            target:
              $ref: '#/components/schemas/target-string'
          required:
            - target
      required:
        - type
        - payload
    aliases:
      title: Array of Alias
      description: |
        Array of zero or more alias resources
      type: array
      items:
        $ref: '#/components/schemas/alias'
  parameters:
    NamespaceId:
      in: path
      name: nsid
      required: true
      schema:
        $ref: '#/components/schemas/namespace-id'
  responses:
    BadRequestErrorResponse:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
    InvalidCredentialsErrorResponse:
      description: |
        Authentication error - invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvalidCredentials'
    PermissionDeniedErrorResponse:
      description: |
        User is not authorized for this operation.

        This error occurs when you try to perform an operation on a resource, and you have permission to access the resource - but you don't have permission to perform the operation. For example, you may be authorized to `GET` the resource but not update it.

        (If you try to perform any operation on a resource you're not authorized to access, the API returns a 404 error.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PermissionDenied'
    NotFoundErrorResponse:
      description: |
        The requested resource was not found or access was denied.

        The API returns an identical error in both scenarios for data privacy reasons: API consumers can't find out anything about resources they aren't authorized to access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
    TooManyRequestsErrorResponse:
      description: |
        Request limit reached. The request was not processed.

        This error occurs when you send too many requests in a short period of time. You should pause before sending further requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequests'
    InternalServerErrorResponse:
      description: Unexpected internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    ServiceUnavailableErrorResponse:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceUnavailable'
