A Resource Definitions describes how and when a resource should be provisioned. It links a driver (the how) along with a Matching Criteria (the when) to a Resource Type. This allows Humanitec to invoke a particular driver for the required Resource Type in the context of a particular Application and Environment. The schema for the `driver_inputs` is defined by the `input_schema` property on the DriverDefinition identified by the `driver_type` property.
openapi: 3.0.0
info:
title: Humanitec AccountType ResourceDefinition 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: ResourceDefinition
x-displayName: Definitions
description: 'A Resource Definitions describes how and when a resource should be provisioned. It links a driver (the how) along with a Matching Criteria (the when) to a Resource Type. This allows Humanitec to invoke a particular driver for the required Resource Type in the context of a particular Application and Environment.
The schema for the `driver_inputs` is defined by the `input_schema` property on the DriverDefinition identified by the `driver_type` property.
<SchemaDefinition schemaRef="#/components/schemas/ResourceDefinitionResponse" />
'
paths:
/orgs/{orgId}/resources/defs:
get:
tags:
- ResourceDefinition
summary: List Resource Definitions.
operationId: listResourceDefinitions
description: Filter criteria can be applied to obtain all the resource definitions that could match the filters, grouped by type and sorted by matching rank. Resources marked as deleted are not listed in the response, unless specified via `deleted` query parameter.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: app
in: query
description: '(Optional) Filter Resource Definitions that may match a specific Application.
'
schema:
type: string
- name: env
in: query
description: '(Optional) Filter Resource Definitions that may match a specific Environment.
'
schema:
type: string
- name: env_type
in: query
description: '(Optional) Filter Resource Definitions that may match a specific Environment Type.
'
schema:
type: string
- name: res
in: query
description: '(Optional) Filter Resource Definitions that may match a specific Resource.
'
schema:
type: string
- name: res_type
in: query
description: '(Optional) Filter Resource Definitions that may match a specific Resource Type.
'
schema:
type: string
- name: class
in: query
description: '(Optional) Filter Resource Definitions that may match a specific Class.
'
schema:
type: string
- name: deleted
in: query
description: If returns also resource definitions which has been deleted.
schema:
type: boolean
default: false
responses:
'200':
description: 'A possibly empty list of Resources Definitions.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ResourceDefinitionResponse'
type: array
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
post:
tags:
- ResourceDefinition
summary: Create a new Resource Definition.
operationId: createResourceDefinition
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
requestBody:
description: 'The Resource Definition details.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResourceDefinitionRequestRequest'
responses:
'200':
description: 'The newly created Resources Definition details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceDefinitionResponse'
'400':
description: 'One or more request parameters is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'A Resources Definition 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}:
get:
tags:
- ResourceDefinition
summary: Get a Resource Definition.
description: If the resource is marked as deleted it is not shown in the response, unless specified via `deleted` query parameter.
operationId: getResourceDefinition
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: deleted
in: query
description: If returns the resource definition even if it has been deleted.
schema:
type: boolean
default: false
responses:
'200':
description: 'The requested Resources Definition details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceDefinitionResponse'
'404':
description: 'A Resource Definition with the ''defId'' ID is not found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
put:
tags:
- ResourceDefinition
summary: Update a Resource Definition.
operationId: updateResourceDefinition
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: 'The Resource Definition record details.
The PUT operation updates a resource definition using the provided payload. An empty driver_account or driver_inputs property will unset the existing values.
If driver_type changes and an Active Resource which uses this Resource Definition exists, the resource provisioned with the previous used driver_type will be deleted.
As driver_type can''t be empty, an empty driver_type means existing value will be used.
Currently the resource can''t be changed.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateResourceDefinitionRequestRequest'
responses:
'200':
description: 'The updated Resource Definition.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceDefinitionResponse'
'400':
description: 'One or more request parameters is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'A Resource Definition with the ''defId'' ID is not found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
delete:
tags:
- ResourceDefinition
summary: Delete a Resource Definition.
operationId: deleteResourceDefinition
description: "If there **are no** Active Resources provisioned via the current definition, the Resource Definition is deleted immediately.\n\nIf there **are** Active Resources provisioned via the current definition, the request fails. The response will describe the changes to the affected Active Resources if operation is forced.\n\nThe request can take an optional `force` query parameter. If set to `true`, the current Resource Definition is deleted immediately even if there are Active Resources linked to it. \nThe Resource Definition that has been marked for deletion cannot be used to provision new resources.\n\nWith the next deployment, matching criteria for Resources will be re-evaluated, and current Active Resources for the target environment would be either linked to another matching Resource Definition or decommissioned and created using the new or default Resource Definition (when available)."
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: force
in: query
description: 'If set to `true`, will mark the Resource Definition for deletion, even if it affects existing Active Resources.
'
schema:
type: boolean
responses:
'204':
description: 'Resource Definition has been marked as deleted.
'
'404':
description: 'A Resource Driver with the ''driverId'' ID is not found or is not accessible by the organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'List of Active Resources that still reference this Resource Definition.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ResourceDefinitionChangeResponse'
type: array
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
patch:
tags:
- ResourceDefinition
summary: Update a Resource Definition.
operationId: patchResourceDefinition
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: 'The Resource Definition record details.
The PATCH operation would change the value of the property if it is included in the request payload JSON, and not `null`. Missing and `null` properties are ignored.
For the map properties, such as PatchResourceDefinitionRequest.DriverInputs, the merge operation is applied.
Merge rules are as follows:
- If a map property has a value, it is replaced (or added).
- If a map property is set to `null`, it is removed.
- If a map property is not included (missing in JSON), it remains unchanged.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchResourceDefinitionRequestRequest'
responses:
'200':
description: 'The updated Resource Definition.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceDefinitionResponse'
'400':
description: 'One or more request parameters is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'A Resource Definition with the ''defId'' ID is not found.
'
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:
put:
tags:
- ResourceDefinition
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:
- ResourceDefinition
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:
- ResourceDefinition
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'
/orgs/{orgId}/resources/defs/{defId}/resources:
get:
tags:
- ResourceDefinition
summary: List Active Resources provisioned via a specific Resource Definition.
operationId: listActiveResourceByDefinition
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
responses:
'200':
description: 'A possibly empty list of Active Resources.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ActiveResourceResponse'
type: array
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
components:
schemas:
CreateResourceDefinitionRequestRequest:
description: CreateResourceDefinitionRequest describes a new ResourceDefinition request.
example:
criteria: []
driver_account: gcp-dev-cloudsql
driver_inputs:
secrets:
dbcredentials:
password: '***'
username: '***'
values:
instance: my-dev-project:my-region:dev-db
driver_type: humanitec/cloudsql
id: dev-postgres
name: Dev Postgres Instance
provision:
aws-policy:
is_dependent: false
dns#my-dns: {}
type: postgres
properties:
criteria:
description: (Optional) The criteria to use when looking for a Resource Definition during the deployment.
items:
$ref: '#/components/schemas/MatchingCriteriaRuleRequest'
type: array
driver_account:
description: (Optional) Security account required by the driver.
pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
type: string
driver_inputs:
$ref: '#/components/schemas/ValuesSecretsRefsRequest'
description: (Optional) Additional input data to be passed to the driver.
driver_type:
description: The driver to be used to create the resource.
type: string
id:
description: The Resource Definition ID.
pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
type: string
name:
description: The display name.
type: string
provision:
additionalProperties:
$ref: '#/components/schemas/ProvisionDependenciesRequest'
description: (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource.
type: object
type:
description: The Resource Type.
type: string
required:
- id
- name
- type
- driver_type
type: object
ActiveResourceResponse:
description: 'Active Resources represent the concrete resources provisioned for an Environment. They are provisioned on the first deployment after a dependency on a particular resource type is introduced into an Environment. In general, Active Resources are only deleted when their introductory Environment is deleted.
Active Resources are provisioned based on a Resource Definition. The Resource Definition describes how to provision a concrete resource based on a Resource Type and metadata about the Environment (for example the Environment Type or the Application ID). The criteria for how to choose a Resource Definition is known as a Matching Criteria. If the Matching Criteria changes or the Resource Definition is deleted, the concrete resource represented by an Active Resource might be deleted and reprovisioned when a deployment occurs in the Environment.'
example:
app_id: test-app
class: default
def_id: gcp-dev-postgres
def_version_id: 01234567-89ab-cdef-0123-4567890abcdef
deploy_id: 172a1013b
env_id: gcp-dev
env_type: development
gu_res_id: 7bd3966c9ff8eaa66c5cce855c03d715857c3440
org_id: test-org
res_id: modules.my-module.externals.my-db
resource:
host: 127.0.0.1
name: db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9
port: 5432
secret_refs:
credentials: orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials
type: postgres
updated_at: '2020-06-23T16:53:12Z'
properties:
app_id:
description: The ID of the App the resource is associated with.
type: string
class:
description: The Resource Class of the resource
type: string
criteria_id:
description: The Matching Criteria ID.
type: string
def_id:
description: The Resource Definition that this resource was provisioned from.
type: string
def_version_id:
description: The Resource Definition Version that this resource was provisioned from.
type: string
target_def_version_id:
description: The Resource Definition Version pinned to this resource to be provisioned from.
type: string
deploy_id:
description: The deployment that the resource was last provisioned in.
type: string
driver_account:
description: (Optional) Security account required by the driver.
type: string
driver_type:
description: The driver to be used to create the resource.
type: string
env_id:
description: The ID of the Environment the resource is associated with.
type: string
env_type:
description: The Environment Type of the Environment specified by env_id.
type: string
gu_res_id:
description: Globally unique resource id
type: string
org_id:
description: the ID of the Organization the Active Resource is associated with.
type: string
res_id:
description: The ID of the resource
type: string
resource:
additionalProperties: true
description: The resource provisioning outputs ('values' only).
type: object
scheduled_deletion:
description: Deletion is scheduled for this resource.
type: boolean
secret_refs:
additionalProperties: true
description: Secret references from the resource provisioning output.
type: object
status:
description: 'Current resource status: ''pending'', ''active'', or ''deleting''.'
type: string
type:
description: The Resource Type of the resource
type: string
updated_at:
description: The time the resource was last provisioned as part of a deployment.
example: '2020-06-22T09:37:23.523Z'
type: string
format: date-time
required:
- org_id
- app_id
- env_id
- env_type
- res_id
- def_id
- def_version_id
- type
- driver_type
- class
- status
- resource
- secret_refs
- updated_at
- deploy_id
- gu_res_id
- scheduled_deletion
type: object
ValuesSecretsRefsRequest:
description: ValuesSecretsRefs stores data that should be passed around split by sensitivity.
example:
secret_refs:
cr
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/humanitec/refs/heads/main/openapi/humanitec-resourcedefinition-api-openapi.yml