Humanitec MatchingCriteria API

openapi: 3.0.0
info:
  title: Humanitec AccountType MatchingCriteria API
  version: 0.28.24
  description: '# Introduction

    The *Humanitec API* allows you to automate and integrate Humanitec into your developer and operational workflows.

    The API is a REST based API. It is based around a set of concepts:


    * Core

    * External Resources

    * Sets and Deltas


    ## Authentication


    Almost all requests made to the Humanitec API require Authentication. See our [Developer Docs on API Authentication](https://developer.humanitec.com/platform-orchestrator/reference/api-references/#authentication) for instructions.


    ## Content Types

    The Humanitec API, unless explicitly specified, only accepts content types of `application/json` and will always return valid `application/json` or an empty response.


    ## Response Codes

    ### Success

    Any response code in the `2xx` range should be regarded as success.


    | **Code** | **Meaning**                         |

    |----------|-------------------------------------|

    | `200`    | Success                             |

    | `201`    | Success, a new resource was created |

    | `204`    | Success, but no content in response |


    _Note: We plan to simplify the interface by replacing 201 with 200 status codes._


    ### Failure

    Any response code in the `4xx` range should be regarded as an error that can be rectified by the client. `5xx` error codes indicate errors that cannot be corrected by the client.


    | **Code** | **Meaning**                                                                                                           |

    |----------|-----------------------------------------------------------------------------------------------------------------------|

    | `400`    | General error. (Body will contain details)                                                                            |

    | `401`    | Attempt to access protected resource without `Authorization` Header.                                                  |

    | `403`    | The `Bearer` or `JWT` does not grant access to the requested resource.                                                |

    | `404`    | Resource not found.                                                                                                   |

    | `405`    | Method not allowed                                                                                                    |

    | `409`    | Conflict. Usually indicated a resource with that ID already exists.                                                   |

    | `422`    | Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected. |

    | `429`    | Too many requests - request rate limit has been reached.                                                              |

    | `500`    | Internal Error. If it occurs repeatedly, contact support.                                                             |

    '
  contact:
    name: Humanitec Support
    email: support@humanitec.com
  x-logo:
    url: humanitec-logo.png
    altText: Humanitec logo
servers:
- url: https://api.humanitec.io/
tags:
- name: MatchingCriteria
  x-displayName: MatchingCriteria
  description: 'Matching Criteria are a set of rules used to choose which Resource Definition to use to provision a particular Resource Type.


    Matching criteria are made up in order of specificity with least specific first:


    - Environment Type (`env_type`)


    - Application (`app_id`)


    - Environment (`env_id`)


    - Resource (`res_id`)


    When selecting matching criteria, the most specific one is selected. In general, this means of all the Matching Criteria fully matching the context, the Matching Criteria Rule with the most specific element filled is chosen. If there is a tie, the next most specific elements are compared and so on until one is chosen.


    **NOTE:**


    Humanitec will reject the registration of matching criteria rules that duplicate rules already present for a Resource Type.

    <SchemaDefinition schemaRef="#/components/schemas/MatchingCriteriaResponse" />

    '
paths:
  /orgs/{orgId}/resources/defs/{defId}/criteria:
    put:
      tags:
      - MatchingCriteria
      summary: Update all Matching Criteria of a Resource Definition.
      operationId: updateResourceDefinitionCriteria
      description: "Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.\n\nFor example, given 3 sets of matching criteria for the same type:\n\n```\n 1. {\"env_type\":\"test\"}\n 2. {\"env_type\":\"development\"}\n 3. {\"env_type\":\"test\", \"app_id\":\"my-app\"}\n```\n\nIf, a resource of that type was needed in an Application `my-app`, Environment `qa-team` with Type `test` and Resource ID `modules.my-module-externals.my-resource`, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific."
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'Matching Criteria rules.


          '
        required: true
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/MatchingCriteriaRuleRequest'
              type: array
            example:
            - env_id: production
      responses:
        '200':
          description: 'The newly added Matching Criteria details.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MatchingCriteriaResponse'
                type: array
        '400':
          description: 'One or more request parameters is missing or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'The Resource Definition is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'A Matching Criteria already exists.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    post:
      tags:
      - MatchingCriteria
      summary: Add a new Matching Criteria to a Resource Definition.
      operationId: createResourceDefinitionCriteria
      description: "Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.\n\nFor example, given 3 sets of matching criteria for the same type:\n\n```\n 1. {\"env_type\":\"test\"}\n 2. {\"env_type\":\"development\"}\n 3. {\"env_type\":\"test\", \"app_id\":\"my-app\"}\n```\n\nIf, a resource of that type was needed in an Application `my-app`, Environment `qa-team` with Type `test` and Resource ID `modules.my-module-externals.my-resource`, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific."
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'Matching Criteria rules.


          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchingCriteriaRuleRequest'
            example:
              env_id: production
      responses:
        '200':
          description: 'The newly added Matching Criteria details.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchingCriteriaResponse'
        '400':
          description: 'One or more request parameters is missing or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'The Resource Definition is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'A Matching Criteria already exists.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/resources/defs/{defId}/criteria/{criteriaId}:
    delete:
      tags:
      - MatchingCriteria
      summary: Delete a Matching Criteria from a Resource Definition.
      operationId: deleteResourceDefinitionCriteria
      description: 'If there **are no** Active Resources that would match to a different Resource Definition when the current Matching Criteria is deleted, the Matching Criteria is deleted immediately.


        If there **are** Active Resources that would match to a different Resource Definition, the request fails with HTTP status code 409 (Conflict). The response content will list all of affected Active Resources and their new matches.


        The request can take an optional `force` query parameter. If set to `true`, the Matching Criteria is deleted immediately. Referenced Active Resources would match to a different Resource Definition during the next deployment in the target environment.'
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      - name: criteriaId
        in: path
        description: 'The Matching Criteria ID.


          '
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: 'If set to `true`, the Matching Criteria is deleted immediately, even if this action affects existing Active Resources.


          '
        schema:
          type: boolean
      responses:
        '204':
          description: 'Record deleted.


            '
        '404':
          description: 'The Resource Definition is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'One or more Active Resources reference the Resource Definition through this Matching Criteria.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ResourceDefinitionChangeResponse'
                type: array
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
components:
  schemas:
    MatchingCriteriaResponse:
      description: 'Matching Criteria are a set of rules used to choose which Resource Definition to use to provision a particular Resource Type.


        Matching criteria are made up in order of specificity with least specific first:


        - Environment Type (`env_type`)


        - Application (`app_id`)


        - Environment (`env_id`)


        - Resource (`res_id`)


        When selecting matching criteria, the most specific one is selected. In general, this means of all the Matching Criteria fully matching the context, the Matching Criteria Rule with the most specific element filled is chosen. If there is a tie, the next most specific elements are compared and so on until one is chosen.


        **NOTE:**


        Humanitec will reject the registration of matching criteria rules that duplicate rules already present for a Resource Type.'
      properties:
        app_id:
          description: (Optional) The ID of the Application that the Resources should belong to.
          type: string
        class:
          description: (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to `default`.
          type: string
        env_id:
          description: (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
          type: string
        env_type:
          description: (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
          type: string
        id:
          description: Matching Criteria ID
          type: string
        res_id:
          description: (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.
          type: string
      required:
      - class
      - id
      type: object
    HumanitecErrorResponse:
      description: HumanitecError represents a standard Humanitec Error
      properties:
        details:
          additionalProperties: true
          type: object
          description: (Optional) Additional information is enclosed here.
        error:
          type: string
          example: API-000
          description: A short code to help with error identification.
        message:
          type: string
          example: Could not validate token
          description: A Human readable message about the error.
      required:
      - error
      - message
      type: object
      example:
        error: API-000
        message: Could not validate token.
    ResourceDefinitionChangeResponse:
      description: ResourceDefinitionChange describes the effects of a Resource Definition or Matching Criteria update/deletion.
      properties:
        app_id:
          description: The ID of the App the resource is associated with.
          type: string
        env_id:
          description: The ID of the Environment the resource is associated with.
          type: string
        from_def:
          description: The Resource Definition that this resource was provisioned from.
          type: string
        res_id:
          description: The ID of the resource
          type: string
        to_def:
          description: The Resource Definition that resource *will be* provisioned from if the change is applied.
          type: string
      required:
      - app_id
      - env_id
      - res_id
      - from_def
      - to_def
      type: object
    MatchingCriteriaRuleRequest:
      description: MatchingCriteriaRule describes Matching Criteria rules.
      properties:
        app_id:
          description: (Optional) The ID of the Application that the Resources should belong to.
          type: string
        class:
          description: (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to `default`.
          type: string
        env_id:
          description: (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
          type: string
        env_type:
          description: (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
          type: string
        res_id:
          description: (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.
          type: string
      type: object
externalDocs:
  description: Find out more about how to use Humanitec in your every-day development work.
  url: https://developer.humanitec.com/
x-tagGroups:
- name: Core
  tags:
  - Agents
  - Application
  - Artefact
  - ArtefactVersion
  - AuditLogs
  - Logs
  - Deployment
  - EnvironmentType
  - Environment
  - Image
  - PublicKeys
  - Organization
  - Registry
  - RuntimeInfo
  - SecretStore
  - Value
  - ValueSetVersion
- name: App Configuration
  tags:
  - Delta
  - Set
  - WorkloadProfile
- name: Resources
  tags:
  - ActiveResource
  - DriverDefinition
  - MatchingCriteria
  - ResourceDefinition
  - ResourceDefinitionVersion
  - ResourceProvision
  - AccountType
  - ResourceAccount
  - ResourceType
  - ResourceClass
- name: Automation
  tags:
  - AutomationRule
  - Event
  - Pipelines
  - PipelineRuns
  - PipelineApprovals
- name: Users
  tags:
  - UserProfile
  - UserRole
  - Group
  - TokenInfo