Humanitec ResourceDefinitionVersion API
A Resource Definition Version represents a version of a Resource Definition.
OpenAPI Specification
openapi: 3.0.0
info:
title: Humanitec AccountType ResourceDefinitionVersion 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: ResourceDefinitionVersion
x-displayName: Definition Versions
description: 'A Resource Definition Version represents a version of a Resource Definition.
<SchemaDefinition schemaRef="#/components/schemas/ResourceDefinitionVersion" />
'
paths:
/orgs/{orgId}/resources/defs/{defId}/versions:
get:
tags:
- ResourceDefinitionVersion
summary: Get Versions of a Resource Definition.
description: "First 50 Versions are kept along with all the Versions referenced by an Active Resource.\n\n To obtain Versions of a deleted Resource Definition, the `deleted` parameter needs to be used."
operationId: listResourceDefinitionVersions
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/defIdPathParam'
- $ref: '#/components/parameters/deletedQueryParam'
- $ref: '#/components/parameters/perPageQueryParam'
- $ref: '#/components/parameters/pageTokenQueryParam'
responses:
'200':
description: 'A list or Resource Definition Version.
'
headers:
Link:
schema:
type: string
description: A list of request links, optionally including a "next" page link for pagination.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ResourceDefinitionVersion'
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: The Resource Definition is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/resources/defs/{defId}/versions/{defVersionId}:
get:
tags:
- ResourceDefinitionVersion
summary: Get a Resource Definition Version.
operationId: getResourceDefinitionVersion
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/defIdPathParam'
- $ref: '#/components/parameters/defVersionIdPathParam'
responses:
'200':
description: The Resource Definition Version with the specified ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceDefinitionVersion'
'404':
description: The Resource Definition Version is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/resources/defs/{defId}/versions/{defVersionId}/actions/archive:
post:
tags:
- ResourceDefinitionVersion
summary: Mark/unmark the Resource Definition Version as archived.
operationId: archiveResourceDefinitionVersion
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/defIdPathParam'
- $ref: '#/components/parameters/defVersionIdPathParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ArchiveDefinitionVersionRequest'
responses:
'204':
description: The Resource Definition Version's archived status changed.
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: The Resource Definition Version is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/resources/defs/{defId}/versions/{defVersionId}/actions/promote:
post:
tags:
- ResourceDefinitionVersion
summary: Promote the Resource Definition Version as active.
operationId: promoteResourceDefinitionVersion
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/defIdPathParam'
- $ref: '#/components/parameters/defVersionIdPathParam'
responses:
'204':
description: The Resource Definition Version became active.
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: The Resource Definition Version is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
components:
parameters:
deletedQueryParam:
name: deleted
in: query
description: If to show also deleted records in the response.
required: false
example: true
schema:
type: boolean
default: false
orgIdPathParam:
name: orgId
in: path
description: The Organization ID
example: sample-org
required: true
schema:
type: string
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
maxLength: 50
defVersionIdPathParam:
name: defVersionId
in: path
description: The Resource Definition Version ID.
example: 01234567-89ab-cdef-0123-4567890abcdef
required: true
schema:
type: string
perPageQueryParam:
name: per_page
in: query
description: The maximum number of items to return in a page of results
required: false
example: 50
schema:
type: integer
minimum: 1
maximum: 100
default: 50
pageTokenQueryParam:
name: page
in: query
description: The page token to request from
required: false
example: AAAAAAAAAA==
schema:
type: string
defIdPathParam:
name: defId
in: path
description: The Resource Definition ID.
example: sample-def
required: true
schema:
type: string
schemas:
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.
ProvisionDependenciesResponse:
description: ProvisionDependencies defines resources which are needed to be co-provisioned with the current resource.
properties:
is_dependent:
description: If the co-provisioned resource is dependendent on the current one.
type: boolean
match_dependents:
description: If the resources dependant on the main resource, are also dependant on the co-provisioned one.
type: boolean
params:
additionalProperties: true
description: (Optional) Additional parameters to be passed to the driver which will provision the resource.
type: object
required:
- is_dependent
type: object
ResourceDefinitionVersion:
description: A Resource Definition Version represents a version of a Resource Definition.
example:
id: 01234567-89ab-cdef-0123-4567890abcdef
org_id: test-org
def_id: dev-postgres
name: Dev Postgres Instance
type: postgres
driver_type: humanitec/postgres-cloudsql
driver_account: gcp-dev-cloudsql
driver_inputs:
secret_refs:
credentials:
password:
value: <secret>
user:
ref: vault/path/to/data/secrets/user
store: my-external-vault
version: '1'
values:
instance: my-dev-project:my-region:dev-db
provision:
aws-policy:
is_dependent: false
match_dependents: false
dns#my-dns: {}
created_at: '2020-05-23T12:32:16Z'
created_by: a.user@example.com
action: created
archived: false
active: true
proposed: false
properties:
id:
description: The Resource Definition Version ID.
type: string
org_id:
description: The Organization ID.
type: string
def_id:
description: The Resource Definition ID.
type: string
name:
description: The display name.
type: string
type:
description: The Resource Type.
type: string
driver_type:
description: The driver to be used to create the resource.
type: string
driver_account:
description: (Optional) Security account required by the driver.
type: string
driver_inputs:
$ref: '#/components/schemas/ValuesSecretsRefsResponse'
description: (Optional) Additional input data to be passed to the driver.
provision:
additionalProperties:
$ref: '#/components/schemas/ProvisionDependenciesResponse'
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
action:
type: string
description: The action that generated the Resource Definition Version. Might be one of `created`, `updated` or `deleted`.
archived:
type: boolean
description: Specifies if the version is archived (i.e. can't be used for a new resource).
active:
type: boolean
description: Specifies if the version is active (i.e. is being used if target version is not specified for a resource or a context).
proposed:
type: boolean
description: Specifies if the version is proposed (i.e. is newer than the active version).
created_at:
description: The timestamp of when this record has been created.
example: '2020-06-22T09:37:23.523Z'
title: Simplified extended ISO format date/time string.
type: string
format: date-time
created_by:
description: The user who created this record.
type: string
required:
- org_id
- id
- name
- def_id
- type
- driver_type
- driver_account
- driver_inputs
- provision
- action
- archived
- active
- proposed
- created_at
- created_by
type: object
ValuesSecretsRefsResponse:
description: ValuesSecretsRefs stores data that should be passed around split by sensitivity.
example:
secret_refs:
credentials:
password:
value: <secret>
user:
ref: vault/path/to/data/secrets/user
store: my-external-vault
version: '1'
secrets:
password: vault/path/to/data/.secrets/password
user: vault/path/to/data/.secrets/user
values:
host: 127.0.0.1
name: my-database
properties:
secret_refs:
additionalProperties: true
description: 'Secrets section of the data set. They can hold sensitive information that will be stored in the primary organization secret store and replaced with the secret store paths when sent outside, or secret references stored in a defined secret store. Can''t be used together with `secrets`.
They can hold a nested structure but leaf objects need to be of type SecretReference, where:
- `store` is a Secret Store id. It can''t be `humanitec`. It''s mandatory if `ref` is defined and can''t be used in request payloads if `value` is defined.
- `ref` is the secret key in the format of the target store. It can''t be used in request payloads if `value` is defined.
- `version` is the version of the secret as defined in the target store. It can be defined only if `ref` is defined.
- `value` is the value to store in the organizations primary secret store. It can''t be used in request payloads if `ref` is defined.'
type: object
secrets:
additionalProperties: true
description: Secrets section of the data set. Sensitive information is stored in the primary organization secret store and replaced with the secret store paths when sent outside. Can't be used together with `secret_refs`.
type: object
values:
additionalProperties: true
description: Values section of the data set. Passed around as-is.
type: object
type: object
ArchiveDefinitionVersionRequest:
example:
archive: true
properties:
archived:
description: Indicates whether to set this version archived or non-archived. Optional, true if not specified.
type: boolean
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