openapi: 3.0.0
servers:
  - url: 'https://api.devbank.apiture.com/apiProducts'
x-note: DO NOT EDIT THIS GENERATED FILE. Edit source file src/openapi/openapi.yaml
x-note-generated-by: openapi-schema-resolver
x-note-generated-on: '2020-10-23T12:45:27-0400'
info:
  title: API Products
  description: >-
    An API to manage API products (built on the Apiture stack) associated with a dev portal. An API product is a collection of one or more
    APIs/services. Client applications are associated with one or more API products.

    An API product consists of

      * zero or more APIs
      * zero or more other API products

    For example, the product _Digital Account Opening_ may be composed of a _Basic Banking_ product plus the _Applications API_ and the _Workflow
    API_.

    Upon creation, an API product is in a `pending` state. It must be activated before it can be selected for use by an application; see the
    `activateApiProduct` operation.
  version: 0.13.2
  contact:
    name: Apiture
    url: 'https://developer.apiture.com'
    email: api@apiture.com
  termsOfService: 'http://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
tags:
  - name: API
    description: Endpoints which describe this API.
  - name: API Product
    description: API Prodcucts
  - name: API Product States
    description: API Product States
paths:
  /inactiveProducts:
    post:
      operationId: deactivateApiProduct
      security:
        - apiKey: []
          accessToken:
            - admin/write
      summary: Deactivate an API product
      tags:
        - API Product States
      description: >-
        Inactivate an API product. This changes the `state` property of the API product to `inactive`. This operation is available via the
        `apiture:deactivate` link on the api product resource, if and only if the API product is eligible for the deactivate operation. A product may
        not be deactivated if it is in use by any other product or client applications, unless the `?force=true` option is used.


        The responses is the updated representation of the API product. The `If-Match` request header value, if used, must match the current entity
        tag value of the API product.
      parameters:
        - $ref: '#/components/parameters/productQueryParam'
        - name: force
          in: query
          description: 'Force deactivation of the product, even if client applications are using the product. This is `false` by default.'
          schema:
            type: boolean
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The API product was updated and its `state` changed to `inactive`.
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/product'
            application/json:
              schema:
                $ref: '#/components/schemas/product'
        '400':
          $ref: '#/components/responses/400DeactivateApiProduct'
        '409':
          $ref: '#/components/responses/409DeactivateApiProductConflict'
  /activeProducts:
    post:
      operationId: activateApiProduct
      security:
        - apiKey: []
          accessToken:
            - admin/write
      summary: Activate an API product
      tags:
        - API Product States
      description: >-
        Update an API product by adding it to the set of active API products. This changes the `state` property of the API product to `active`. This
        operation is available via the `apiture:activate` link on the api product resource, if and only if the API product is eligible for the
        activate operation. The responses is the updated representation of the API product. The `If-Match` required request header value must match
        the current entity tag value of the API product.
      parameters:
        - $ref: '#/components/parameters/productQueryParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The API product was updated and its `state` changed to `active`.
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/product'
            application/json:
              schema:
                $ref: '#/components/schemas/product'
        '400':
          $ref: '#/components/responses/400ActivateApiProduct'
        '409':
          $ref: '#/components/responses/409ActivateApiProductConflict'
  /products:
    get:
      summary: Return a collection of API products
      description: >-
        Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [filterable](http://developer.apiture.com/docs/concepts/filtering)
        collection of API products. The [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links.
      operationId: getApiProducts
      security:
        - apiKey: []
      x-apiture-implemented: true
      tags:
        - API Product
      parameters:
        - $ref: '#/components/parameters/startQueryParam'
        - name: limit
          in: query
          description: The maximum number of API product representations to return in this page.
          schema:
            type: integer
            format: int32
            default: 100
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/stateQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/products'
            application/json:
              schema:
                $ref: '#/components/schemas/products'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
    post:
      summary: Create a new API product
      description: >-
        Create a new API product in the API products collection. The tag is required and must be unique.

        Upon creation, an API product is in a `pending` state. It must be activated before it can be selected for use by an application; see the
        `activateApiProduct` operation.
      operationId: createApiProduct
      security:
        - apiKey: []
          accessToken:
            - admin/write
      x-apiture-implemented: true
      tags:
        - API Product
      responses:
        '201':
          description: Created
          headers:
            Location:
              description: >-
                The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
                *`scheme`*`://host`
              schema:
                type: string
                format: uri
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/product'
            application/json:
              schema:
                $ref: '#/components/schemas/product'
        '400':
          description: Bad Request. One of the request parameters to create a productType  was not valid. See _error for more information
          x-apiture-errors:
            - malformedRequestBody
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '409':
          $ref: '#/components/responses/409ProductExists'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/product'
          application/json:
            schema:
              $ref: '#/components/schemas/product'
        description: The data necessary to create a new API product.
        required: true
  '/products/{productId}':
    get:
      summary: Fetch a representation of this API product
      description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this API product resource.'
      operationId: getApiProduct
      security:
        - apiKey: []
      x-apiture-implemented: true
      tags:
        - API Product
      parameters:
        - $ref: '#/components/parameters/productIdPathParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update this API product resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/product'
            application/json:
              schema:
                $ref: '#/components/schemas/product'
        '304':
          $ref: '#/components/responses/304'
        '404':
          $ref: '#/components/responses/404Product'
    put:
      summary: Update this API product
      description: Perform a complete replacement of this API product.
      operationId: updateApiProduct
      security:
        - apiKey: []
          accessToken:
            - admin/write
      x-apiture-implemented: true
      tags:
        - API Product
      parameters:
        - $ref: '#/components/parameters/productIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update this API product resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/product'
            application/json:
              schema:
                $ref: '#/components/schemas/product'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404Product'
        '412':
          $ref: '#/components/responses/412'
        '422':
          $ref: '#/components/responses/422'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/product'
          application/json:
            schema:
              $ref: '#/components/schemas/product'
        required: true
    patch:
      summary: Update this API product
      description: >-
        Perform a partial update of this API product. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if
        included.
      operationId: patchApiProduct
      security:
        - apiKey: []
          accessToken:
            - admin/write
      x-apiture-implemented: true
      tags:
        - API Product
      parameters:
        - $ref: '#/components/parameters/productIdPathParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update this API product resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/product'
            application/json:
              schema:
                $ref: '#/components/schemas/product'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404Product'
        '412':
          $ref: '#/components/responses/412'
        '422':
          $ref: '#/components/responses/422'
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/product'
          application/json:
            schema:
              $ref: '#/components/schemas/product'
        required: true
    delete:
      summary: Delete this API product resource
      description: Delete this API product resource and any resources that are owned by it. A product must be inactive before it may be deleted.
      operationId: deleteApiProduct
      security:
        - apiKey: []
          accessToken:
            - admin/delete
      x-apiture-implemented: true
      tags:
        - API Product
      parameters:
        - $ref: '#/components/parameters/productIdPathParam'
      responses:
        '204':
          $ref: '#/components/responses/204Deleted'
        '409':
          $ref: '#/components/responses/409NotDeletable'
  /:
    get:
      summary: Top-level resources and operations in this API
      description: Return links to the top-level resources and operations in this API.
      operationId: getApi
      security:
        - apiKey: []
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/root'
            application/json:
              schema:
                $ref: '#/components/schemas/root'
      tags:
        - API
  /apiDoc:
    get:
      summary: Return API definition document
      description: Return the OpenAPI document that describes this API.
      operationId: getApiDoc
      security:
        - apiKey: []
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
            application/openapi+json;version=2.0:
              schema:
                type: object
            application/openapi+yaml;version=2.0:
              schema:
                type: object
            application/hal+json:
              schema:
                type: object
      tags:
        - API
x-apiture-errors:
  accessDenied:
    description: The credentials supplied in the request are insufficient to grant access
    remediation: Check the supplied credentials for validity
  deleteApiProductInvalidState:
    description: API Products may only be deleted if they are in a inactive state
    remediation: Check the state of your API Product and the applicable allowed state transitions in the API Products documentation
  invalidProductId:
    description: No Products were found for the specified productId
    remediation: Check to make sure that the supplied productId corresponds to an apiture product resource
    attributes:
      properties:
        id:
          type: string
          description: The ID of an API product is not found.
  apiProductExists:
    description: 'A product with the specified name, tag, and version already exists.'
    remediation: New products should have unique names or versions.
    attributes:
      properties:
        name:
          type: string
          description: The existing product name.
        version:
          type: string
          description: The existing product version.
          format: semantic-version
  malformedRequestBody:
    description: The supplied request body was malformed
    remediation: Check to make sure that your request body exists and that it does not contain syntax errors
  apiProductInUse:
    description: The API product cannot be deactivated because it is in use by an existing product or client application.
    remediation: 'Wait until the product is not in use before deactivating it, or use the `?force=true` option to bypass this check.'
    attributes:
      properties:
        products:
          description: An array of IDs of products which use this product. This may not be a complete list.
          type: array
          items:
            type: string
        applications:
          description: An array of IDs of client applications  which use this product. This may not be a complete list.
          type: array
          items:
            type: string
x-apiture-traits:
  - api:
      title: API Products
      basePath: apiProducts
      links:
        - getApi
        - getApiDoc
        - getApiProducts
        - createApiProduct
      applied: true
  - resource:
      name: product
      description: >-
        An API product (a combination of Apiture API services and other product elements) which partner developers can access and license when
        building client applications.
      simpleModelSchema: true
      sortable: false
      searchable: false
      cursor: true
      applied: true
  - state:
      name: product
      state: active
      verb: activate
      applied: true
  - state:
      name: product
      state: inactive
      verb: deactivate
      applied: true
components:
  schemas:
    product:
      title: API Product
      description: 'API products, which are composed of APIs (with specific versions) and/or other API products.'
      example:
        _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
        _profile: 'https://api.apiture.com/schemas/apiProducts/product/v1.0.0/profile.json'
        tag: digital-account-Opening
        name: Digital Account Opening
        description: >-
          Supports opening accounts in a fully digital, self-service manner. Clients complete an application on-line, following full regulatory
          guidelines, to open a new account for a banking product, optionally funding the account from an outside funding source.
        version: 1.0.0
        apis:
          - name: Account Applications
            basePath: /accountApplications
            version: 1.0.0
            description: Manages the data and workflow for applications for new banking accounts
          - name: Workflow
            basePath: /workflow
            version: 1.0.0
            description: 'Business processes, included automatic and manual human-driven tasks, such as filling in forms or approving activities'
        products:
          - name: Basic Banking
            _links:
              self: 'https://api.developer.apiture.com/apiProducts/products/43f271c2-190a-45e1-b332-bdf0b11a92bb'
        _links:
          self:
            href: 'https://api.developer.apiture.com/apiProducts/products/43f271c2-190a-45e1-b332-bdf0b11a92bb'
          'apiture:activate':
            href: 'https://api.developer.apiture.com/apiProducts/activeProducts?product=43f271c2-190a-45e1-b332-bdf0b11a92bb'
          'apiture:deactivate':
            href: 'https://api.developer.apiture.com/apiProducts/inactiveProducts?product=43f271c2-190a-45e1-b332-bdf0b11a92bb'
      x-apiture-links:
        'apiture:deactivate':
          rel: 'apiture:deactivate'
          operationId: deactivateApiProduct
          title: Deactivate an API product
          verb: post
          path: /inactiveProducts
          description: >-
            Deactivate an API product by adding it to the set of inactive api products. This changes the `state` property of the API product to
            `inactive`. This operation is available if and only if the API product is eligible for the deactivate operation. The response is the
            updated representation of the API product.
        'apiture:activate':
          rel: 'apiture:activate'
          operationId: activateApiProduct
          title: Activate an API product
          verb: post
          path: /activeProducts
          description: >-
            Activate an API product by adding it to the set of active api products. This changes the `state` property of the API product to `active`.
            This operation is available if and only if the API product is eligible for the activate operation. The response is the updated
            representation of the API product.
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - _id
            - name
            - tag
            - description
            - version
            - state
            - products
            - apis
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        _id:
          type: string
          description: This API product's unique ID.
          readOnly: true
        name:
          description: The name of the API product.
          type: string
          minLength: 6
          maxLength: 64
          example: Digital Banking
        tag:
          description: >-
            A unique read-only alphanumeric identifier for this product. When combined with the `version`, this creates a unique, immutable, durable,
            and human-readable identifier for this product.
          type: string
          minLength: 6
          maxLength: 64
          example: digital-banking
          readOnly: true
          pattern: '[a-z][-_a-z0-9A-Z]{0-63}'
        description:
          description: The description of the client application.
          type: string
          format: markdown
          maxLength: 512
        version:
          description: The semantic version of the product.
          type: string
          format: semantic-version
        state:
          description: >-
            The state of this API product. The default state is `pending`. The product must be _activated_ in order for an application to use the
            product. Use the `POST` HTTP method on the corresponding `activateApiProduct` and `deactivateApiProduct to activate or deactivate the API
            product.
          type: string
          enum:
            - pending
            - active
            - inactive
        products:
          description: An array of products that this composite product contains. Some products are made as assemblies of other products.
          type: array
          items:
            $ref: '#/components/schemas/productRef'
        apis:
          description: Specific APIs that are elements of this product.
          type: array
          items:
            $ref: '#/components/schemas/api'
      type: object
      x-apiture-flattened: true
    productRef:
      title: Product Reference
      description: A concise reference to an API product.
      required:
        - name
        - version
        - _links
      properties:
        name:
          description: The name of the API product.
          type: string
          minLength: 6
          maxLength: 64
          readOnly: true
        version:
          description: The semantic version of the product.
          type: string
          format: semantic-version
          readOnly: true
        _links:
          description: The `self` link of an API product resource.
          type: object
          $ref: '#/components/schemas/links'
      example:
        name: Basic Banking
        version: 1.2.5
        _links:
          self:
            href: 'https://api.developer.apiture.com/apiProducts/products/43f271c2-190a-45e1-b332-bdf0b11a92bb'
      type: object
      x-apiture-flattened: true
    api:
      title: API
      description: An API is a component of an API product.
      type: object
      properties:
        name:
          description: The name of the API product.
          type: string
          minLength: 6
          maxLength: 64
        description:
          description: The description of the API product.
          type: string
          format: markdown
        basePath:
          description: The base path of the API (from the `basePath` in the OpenAPI definition).
          type: string
          minLength: 4
          maxLength: 32
        version:
          description: The semantic version of the API (from the `info.version` in the OpenAPI definition).
          type: string
          format: semantic-version
      example:
        name: Accounts
        basePath: /accounts
        description: 'Access internal accounts and account details (balances, etc.) at a financial institution, as well as linked external accounts'
        version: 1.0.0
      x-apiture-flattened: true
    products:
      title: API Product Collection
      description: |-
        Collection of API products. The items in the collection are ordered in the `_embedded.items` array; the `name` is `apiProducts`.
         The top-level `_links` object may contain pagination links: `self`, `next`, `prev`, `first`, `last`, `collection`.
      example:
        _profile: 'https://api.apiture.com/schemas/apiProducts/products/v1.0.0/profile.json'
        start: g434ljkf430
        limit: 10
        name: apiProducts
        _links:
          self:
            href: /apiProducts/products?start=g434ljkf430&limit=10
          next:
            href: /apiProducts/products?start=p4900sk3df9&limit=10
          collection:
            href: /apiProducts/products
        _embedded:
          items:
            anyOf:
              - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
                _profile: 'https://api.apiture.com/schemas/apiProducts/apiProduct/v1.0.0/profile.json'
                _links:
                  self:
                    href: /apiProducts/products/0399abed-fd3d-4830-a88b-30f38b8a365c
              - _id: d62c0701-0d74-4836-83f9-ebf3709442ea
                _profile: 'https://api.apiture.com/schemas/apiProducts/apiProduct/v1.0.0/profile.json'
                _links:
                  self:
                    href: /apiProducts/products/d62c0701-0d74-4836-83f9-ebf3709442ea
      x-apiture-composition:
        - $ref: '#/components/schemas/cursorPagedCollection'
        - properties:
            - _embedded
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          type: object
          description: Embedded resources.
          properties:
            items:
              description: An array containing a page of API product items.
              type: array
              items:
                $ref: '#/components/schemas/product'
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        start:
          description: >-
            An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
            to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
          type: string
        limit:
          description: The maximum number of items per page.
          type: integer
        name:
          description: A name for the items in collection.
          type: string
      type: object
      x-apiture-flattened: true
    errorResponse:
      x-apiture-version: 2.0.0
      title: Error Response (v2.0.0)
      description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.'
      example:
        _profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
        _error:
          _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
          message: The value for deposit must be greater than 0.
          statusCode: 422
          type: positiveNumberRequired
          attributes:
            value: -125.5
          remediation: Provide a value which is greater than 0
          occurredAt: '2018-01-25T05:50:52.375Z'
          _links:
            describedby:
              href: 'https://api.apiture.com/errors/positiveNumberRequired'
          _embedded:
            errors: []
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
      type: object
      x-apiture-flattened: true
    root:
      x-apiture-version: 2.0.0
      title: API Root (v2.0.0)
      description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.'
      example:
        id: apiName
        name: API name
        apiVersion: 1.0.0
        _profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
        _links: {}
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - _id
            - name
            - apiVersion
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        _id:
          description: This API's unique ID.
          readOnly: true
          type: string
        name:
          type: string
          description: This API's name.
        apiVersion:
          type: string
          description: This API's version.
      type: object
      x-apiture-flattened: true
    abstractResource:
      x-apiture-version: 2.0.0
      title: Abstract Resource (v2.0.0)
      description: >-
        An abstract schema used to define other schemas for request and response bodies. This is a
        [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either
        optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was
        successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded`
        or any data fields, only `_error` and optionally `_links`.
      example:
        _profile: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/profile.json'
        _links:
          self:
            href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractRequest'
        - properties:
            - _error
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
      type: object
      x-apiture-flattened: true
    links:
      title: Links (v1.0.0)
      x-apiture-version: 1.0.0
      description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
      type: object
      x-apiture-key: linkRelationName
      additionalProperties:
        $ref: '#/components/schemas/link'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
      x-apiture-namespace: common
      properties: {}
      x-apiture-flattened: true
    cursorPagedCollection:
      x-apiture-version: 2.0.0
      title: Cursor Paged Collection (v2.0.0)
      description: >-
        A collection of resources, or a page from a larger collection. This is an abstract model schema which is extended to define specific resource
        collections. Pages are referenced using an opaque string starting point named `start`. The `_links` in the collection may contain [pagination
        links](https://developer.apiture.com/docs/concepts/pagination):

          * the `next` link returns the next page of items. If there is no `next`
          link, the collection has been exhausted.
          * the `first` link returns to the beginning
          of the filtered/sorted collection.
          * the `collection` link returns
          to the beginning of the default collection with no explicit filter
          or sort criteria.

        Cursor paged collections can only paginate forwards contiguously (without skipping items or pages), or reset to the beginning of the
        collection. This pagination works for collections which are likely to change during pagination, such as adding data to the beginning of the
        collection's natural sort order. Examples include transactions or audit records.
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/cursorPagedCollection/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - start
            - limit
            - name
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        start:
          description: >-
            An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
            to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
          type: string
        limit:
          description: The maximum number of items per page.
          type: integer
        name:
          description: A name for the items in collection.
          type: string
      type: object
      x-apiture-flattened: true
    abstractRequest:
      x-apiture-version: 2.0.0
      title: Abstract Request (v2.0.0)
      description: >-
        An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
        representation, minus the `_error` defined in `abstractResource`.
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
      example:
        _profile: 'https://api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json'
        _links:
          self:
            href: 'https://api.devbank.apiture.com/applications/'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    error:
      x-apiture-version: 2.0.0
      title: Error (v2.0.0)
      description: Describes an error in an API request or in a service called via the API.
      required:
        - message
      properties:
        message:
          type: string
          description: A localized message string describing the error condition.
        _id:
          description: >-
            A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
            the source of the error). This is is an opaque string.
          readOnly: true
          type: string
        statusCode:
          description: The HTTP status code associate with this error.
          type: integer
          minimum: 100
          maximum: 599
          example: 422
        type:
          type: string
          description: >-
            An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
            render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
            Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
            `stringValueNotInAllowedSet`.
        occurredAt:
          type: string
          format: date-time
          description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
          example: '2018-02-02T03:37:15.375Z'
        attributes:
          description: >-
            Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
            `minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
            client/presentation tier). The set of attributes varies by error `type`.
          allOf:
            - $ref: '#/components/schemas/attributes'
        remediation:
          type: string
          description: An optional localized string which provides hints for how the user or client can resolve the error.
        errors:
          description: An optional array of nested error objects. This property is not always present.
          type: array
          items:
            $ref: '#/components/schemas/error'
        _links:
          $ref: '#/components/schemas/links'
      example:
        _id: 2eae46e1575c0a7b0115a4b3
        message: Descriptive error message...
        statusCode: 422
        type: errorType1
        remediation: Remediation string...
        occurredAt: '2018-01-25T05:50:52.375Z'
        errors:
          - _id: ccdbe2c5c938a230667b3827
            message: An optional embedded error
          - _id: dbe9088dcfe2460f229338a3
            message: Another optional embedded error
        _links:
          describedby:
            href: 'https://developer.apiture.com/errors/errorType1'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    link:
      x-apiture-version: 1.0.0
      title: Link (v1.0.0)
      description: >-
        Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
        links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture
        links _may_ include a `method` property.
      required:
        - href
      properties:
        href:
          type: string
          format: uri
          description: The URI or URI template for the resource/operation this link refers to.
        type:
          type: string
          description: The media type for the resource.
        templated:
          type: boolean
          description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).'
        title:
          type: string
          description: An optional human-readable localized title for the link.
        deprecation:
          type: string
          format: uri
          description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.'
        profile:
          type: string
          format: uri
          description: 'The URI of a profile document, a JSON document which describes the target resource/operation.'
      example:
        href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f'
        title: Application
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    attributes:
      x-apiture-version: 2.0.0
      title: Attributes (v2.0.0)
      description: An optional map of name/value pairs which contains additional dynamic data about the resource.
      type: object
      x-apiture-key: attributeName
      additionalProperties:
        $ref: '#/components/schemas/attributeValue'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
      x-apiture-namespace: common
      properties: {}
      x-apiture-flattened: true
    attributeValue:
      x-apiture-version: 2.0.0
      title: Attribute Value (v2.0.0)
      description: The data associated with this attribute.
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      properties: {}
      x-apiture-flattened: true
  responses:
    '304':
      description: Not Modified. The resource has not been modified since it was last fetched.
    '400':
      description: >-
        Bad Request. The request body or one or more of the query parameters was not well formed.  The `_error` field in the response will contain
        details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '412':
      description: >-
        Precondition Failed. The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has
        changed in the interim.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '422':
      description: >-
        Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will
        contain details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    204Deleted:
      description: No Content. The resource was deleted successfully.
    400DeactivateApiProduct:
      description: Bad Request. The apiProduct parameter was malformed or does not refer to an existing or accessible API product.
      x-apiture-errors:
        - apiProductRefNotFound
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    400ActivateApiProduct:
      description: Bad Request. The apiProduct parameter was malformed or does not refer to an existing or accessible API product.
      x-apiture-errors:
        - apiProductRefNotFound
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    404Product:
      description: >-
        Not Found. There is no such API product resource at the specified `{productId}`. The `_error` field in the response will contain details about
        the request error.
      x-apiture-errors:
        - invalidProductId
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409ProductExists:
      description: Conflict. An API product already exists with specified `tag`.
      x-apiture-errors:
        - apiProductExists
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409NotDeletable:
      description: Conflict. The product may not be deleted if the state is `inactive`.
      x-apiture-errors:
        - deleteApiProductInvalidState
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409DeactivateApiProductConflict:
      description: >-
        Conflict. The request to change the state of the API product is not allowed. Examples include when a product is in use by another product or
        the product is used by an active client application. The `_error` field in the response will contain details about the request error.
      x-apiture-errors:
        - apiProductInUse
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409ActivateApiProductConflict:
      description: >-
        Conflict. The request to change the state of the API product is not allowed. The `_error` field in the response will contain details about the
        request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
  parameters:
    productQueryParam:
      name: product
      required: true
      in: query
      description: >-
        A string which uniquely identifies an API product which is to added to the active API products resource set. This may be the unique API
        product ID or the URI of the API product.
      schema:
        type: string
    productIdPathParam:
      name: productId
      description: The unique identifier of this API product. This is an opaque string.
      in: path
      required: true
      schema:
        type: string
    startQueryParam:
      name: start
      in: query
      description: >-
        Represents the first record of the page of results. This is supplied by the service when paginating items: the `next` link includes a
        `?start=` query parameter which refers to beginning of the next page of items.
      schema:
        type: string
    filterQueryParam:
      name: filter
      in: query
      description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).'
      schema:
        type: string
    stateQueryParam:
      name: state
      in: query
      description: >-
        Subset the resources to only those whose `state` matches the query, such as `?state=active`. The value may be a `|` separated list of states,
        such as `?state=pending|active` to match all resources whose `state` is either `pending` _or_ `active`. If `?filter=` is also used, the two
        are combined with an implicit `and()` operation.
      style: pipeDelimited
      schema:
        type: array
        items:
          type: string
          enum:
            - pending
            - active
            - inactive
    ifMatchHeaderParam:
      name: If-Match
      description: 'The entity tag that was returned in the `ETag` response. If passed, this must match the current entity tag of the resource.'
      in: header
      schema:
        type: string
    ifNoneMatchHeaderParam:
      name: If-None-Match
      description: >-
        The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not
        Modified) and no response body, else the resource representation will be returned.
      in: header
      schema:
        type: string
  requestBodies:
    product:
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/product'
        application/json:
          schema:
            $ref: '#/components/schemas/product'
      required: true
  securitySchemes:
    apiKey:
      type: apiKey
      name: API-Key
      in: header
      description: >-
        API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
        `API-Key: {api-key}` request header.
    accessToken:
      type: oauth2
      description: >-
        OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private
        `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then
        passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also
        returns a refresh token which the client should use to renew the access token before it expires.
      flows:
        authorizationCode:
          authorizationUrl: /auth/oauth2/authorize
          tokenUrl: /auth/oauth2/token
          scopes:
            admin/write: Write (update) access to API products.
            admin/delete: Delete access to API products.
            admin/full: Full access to API products.
