DriverDefinition describes the resource driver. Resource Drivers are code that fulfils the Humanitec Resource Driver Interface. This interface allows for certain actions to be performed on resources such as creation and destruction. Humanitec provides numerous Resource Drivers “out of the box”. It is also possible to use 3rd party Resource Drivers or write your own.
openapi: 3.0.0
info:
title: Humanitec AccountType DriverDefinition 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: DriverDefinition
x-displayName: Resource Drivers
description: 'DriverDefinition describes the resource driver.
Resource Drivers are code that fulfils the Humanitec Resource Driver Interface. This interface allows for certain actions to be performed on resources such as creation and destruction. Humanitec provides numerous Resource Drivers “out of the box”. It is also possible to use 3rd party Resource Drivers or write your own.
<SchemaDefinition schemaRef="#/components/schemas/DriverDefinitionResponse" />
'
paths:
/orgs/{orgId}/resources/drivers:
get:
tags:
- DriverDefinition
summary: List Resource Drivers.
operationId: listResourceDrivers
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'A possibly empty list of Resources Drivers.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/DriverDefinitionResponse'
type: array
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
post:
tags:
- DriverDefinition
summary: Register a new Resource Driver.
operationId: createResourceDriver
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
requestBody:
description: 'Resources Driver details.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDriverRequestRequest'
responses:
'200':
description: 'The newly registered Resources Driver details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/DriverDefinitionResponse'
'400':
description: 'One or more request parameters is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'A Resources Driver 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/drivers/{driverId}:
get:
tags:
- DriverDefinition
summary: Get a Resource Driver.
operationId: getResourceDriver
description: '# Only drivers that belongs to the given organization or registered as `public` are accessible through this endpoint'
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: driverId
in: path
description: 'The Resource Driver ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'The requested Resources Driver details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/DriverDefinitionResponse'
'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'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
put:
tags:
- DriverDefinition
summary: Update a Resource Driver.
operationId: updateResourceDriver
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: driverId
in: path
description: 'The Resource Driver ID.
'
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDriverRequestRequest'
responses:
'200':
description: 'The updated Resources Driver details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/DriverDefinitionResponse'
'400':
description: 'One or more request parameters is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'A Resources Driver with the ''driverId'' 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:
- DriverDefinition
summary: Delete a Resources Driver.
operationId: deleteResourceDriver
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: driverId
in: path
description: 'The Resources Driver ID to delete.
'
required: true
schema:
type: string
responses:
'204':
description: 'Record deleted.
'
'409':
description: 'Resource driver is used by some active resources.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
components:
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.
CreateDriverRequestRequest:
description: CreateDriverRequest describes the new resource driver registration request.
example:
account_types:
- gcp
- aws
id: route53
inputs_schema: {}
is_public: false
target: https://drivers.example.com/route53/
template: ''
type: dns
properties:
account_types:
description: List of resources accounts types supported by the driver
items:
type: string
type: array
id:
description: The ID for this driver. Is used as `driver_type`.
pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
type: string
inputs_schema:
additionalProperties: true
description: A JSON Schema specifying the driver-specific input parameters.
type: object
target:
description: The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see 'target'.
type: string
template:
description: If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver.
type:
description: The type of resource produced by this driver
type: string
is_public:
type: boolean
deprecated: true
required:
- id
- type
- target
- inputs_schema
- account_types
type: object
DriverDefinitionResponse:
description: 'DriverDefinition describes the resource driver.
Resource Drivers are code that fulfils the Humanitec Resource Driver Interface. This interface allows for certain actions to be performed on resources such as creation and destruction. Humanitec provides numerous Resource Drivers “out of the box”. It is also possible to use 3rd party Resource Drivers or write your own.'
example:
account_types:
- gcp
- aws
id: route53
inputs_schema: {}
is_public: false
org_id: test-org
target: https://drivers.example.com/route53/
template: ''
type: dns
properties:
account_types:
description: List of resources accounts types supported by the driver
items:
type: string
type: array
id:
description: The ID for this driver. Is used as `driver_type`.
type: string
inputs_schema:
additionalProperties: true
description: A JSON Schema specifying the driver-specific input parameters.
type: object
org_id:
description: The Organization this driver exists under. Useful as public drivers are accessible to other orgs.
type: string
target:
description: The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see `target`.
type: string
template:
description: If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver.
type:
description: The type of resource produced by this driver
type: string
required:
- org_id
- id
- type
- inputs_schema
- account_types
type: object
UpdateDriverRequestRequest:
description: UpdateDriverRequest describes the update driver details request.
example:
account_types:
- gcp
- aws
inputs_schema: {}
is_public: false
target: https://drivers.example.com/route53/
template: '{{ mustToRawJson .driver }}'
type: dns
properties:
account_types:
description: List of resources accounts types supported by the driver
items:
type: string
type: array
inputs_schema:
additionalProperties: true
description: A JSON Schema specifying the driver-specific input parameters.
type: object
target:
description: The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see 'target'.
type: string
template:
description: If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver.
type:
description: The type of resource produced by this driver
type: string
is_public:
type: boolean
deprecated: true
required:
- type
- target
- inputs_schema
- account_types
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