> ## Documentation Index
> Fetch the complete documentation index at: https://platform.docs.zenoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin API

> The Admin API provides a REST API for the Component repository and api key secrets.

# Admin API

The **Admin API** provides a REST API for the Component repository and api key secrets.

The access to **Admin API** is restricted using HTTP basic authentication, see [Admin API security](/technical-specification/hub-backend/customization#admin-api-security).

## Query component

#### GET /api/component/\{name}

Retrieves a registered component by **name**. Name can be a full name, including a revision after `:` delimiter.
If revision part of the name is not included, the latest version is queried.

##### Response:

* **200 OK**, a success response with Hub component resource as a body,
* **404 Not Found**, a component with *name* not found.

## Query component dependencies

#### GET /api/component/\{name}/dependencies

Retrieves a dependency tree of a registered component by **name**. Name can be a full name, including a revision after `:` delimiter.
If revision part of the name is not included, the latest version is queried.

##### Response:

* **200 OK**, a success response with dependency tree resource as a body,
* **404 Not Found**, a component with *name* not found.

## Register component

#### POST /api/component

Registers a new component. A component must pass a DSL validation process before successful registration.

##### Request:

* **name** a component name,
* **revision** a component version, generated if ommitted,
* **definition** a component definition using [Component DSL](/technical-specification/hub-backend/components#component-dsl).
* **config** a component configuration
* **configSchema** a component configuration JSON schema
* **metadata** a map of component metadata
* **authToken** API key used for authenticating component access via. [Client API](/technical-specification/hub-backend/client-api#execute-exposed-function)

##### Response:

* **201 Created**, a success response with a reference to a newly registered component:
  * `/api/components/{name}` as a Location header,
  * [Component Id](#component-id) as body.
* **400 Bad Request**, if component validation fails.

## Delete component

#### DELETE /api/component/\{name}

Deletes a registered component by **name**. Name can be a full name, including a revision after `:` delimiter.
In that case only specified revision of component is deleted. If revision part of the name is not included,
all versions of the component are deleted.
**Important:** Deleting a component/revision does not check if there are any components depending on it. It's up to
the API consumer to make sure that the component/revision is not used by any other components and therefore deleting
it does not break any flows.

##### Response:

* **200 OK**, a success response with list of component ids of deleted revisions as a body,
* **404 Not Found**, a component with *name* not found.

## Query component dependencies

#### GET /api/component/\{name}/dependencies

Retrieves a dependency tree of a registered component by **name**. Name can be a full name, including a revision after `:` delimiter.
If revision part of the name is not included, the latest version is queried.

##### Response:

* **200 OK**, a success response with dependency tree resource as a body,
* **404 Not Found**, a component with *name* not found.

## Register target

#### POST /api/target

Registers a new target. Target is a specific component that just declares a dependency and its configuration.
It must pass a DSL validation process before successful registration.

##### Request:

* **targetName** a name of the target, optional (generated if missing),
* **targetRevision** a target revision, optional (generated if missing),
* **componentName** a name of a parent component, mandatory,
* **componentRevision** a version of the parent component, optional (the latest one is used if missing),
* **executableName** a name of workflow or function from the parent component to run when the target is executed, mandatory,
* **executableType** a type of executable from the parent component, it has to be either 'function' or 'workflow', mandatory.
* **metadata** a map of target component metadata

##### Response:

* **201 Created**, a success response with a reference to a newly registered target:
  * `/api/components/{name}` as a Location header,
  * [Component Id](#component-id) as body.
* **400 Bad Request**, if target validation fails.

## Component Configuration

### Query component configuration

#### GET /api/component/\{name}/config

Retrieves a component configuration for a given component **name**.

##### Response:

* **200 OK**, a success response with the component configuration as body,
* **404 Not Found**, a component configuration with *name* not found.

### Store component configuraton

#### POST /api/component/\{name}/config

Stores a component configuration using a given component **name**.

##### Request:

The request body contains a component configuration as JSON.

##### Response:

* **201 Created**, a success response with [Component Configuration Id](#component-configuration-id) as body,

## Test executable

#### POST /api/test/\{executableType}/\{fullName}

Creates a request to start a new execution of a workflow or a function directly, without the need to create a target.

* **executableType**: can be either workflow or function.
* **fullName**: a name of a workflow or a function to start including component id.

##### Request:

* **config**: a configuration for the component.
* **input**: an execution input.

##### Response:

* **201 Created**, a success response has a *request URI* as a Location header and the body contains the newly
  created request as [Execution Request resource](/technical-specification/hub-backend/client-api#execution-request)

The corresponding response can be one of the following:

* [Route resource](/technical-specification/hub-backend/client-api#route),
* [Result resource](/technical-specification/hub-backend/client-api#result),
* [Validation Error resource](/technical-specification/hub-backend/client-api#validation-error),
* [Execution Error resource](/technical-specification/hub-backend/client-api#execution-error).

## API Keys

### Query api key

#### GET /api/api-key/\{id}

Retrieves a registered component by **id**. Id is a randomly generated UUID assigned to api key when created.

##### Response:

* **200 OK**, a success response with api key resource as a body,
* **404 Not Found**, a api key with *id* not found.

### Create new api key

#### POST /api/api-key/

Registers a new api-key.

##### Request:

[Api Key](#api-key) resource.

##### Response:

* **200 OK**, a success response with an id of a newly registered component as body.
* **400 Bad Request**, if api key is data are not valid (no token or permissions are wrong).

### Delete api-key

#### DELETE /api/api-key/\{id}

Delete a registered api key by **id**.

##### Response:

* **204 No Content**, a success response with no content,
* **404 Not Found**, an api key with *id* not found.

### Update api key

#### POST /api/api-key/\{id}

Updates an existing api-key.

##### Request:

[Api Key](#api-key) resource with updated fields.

##### Response:

* **200 OK**, a success response with an id of a newly registered component as body.
* **400 Bad Request**, if api key is data are not valid (no token or permissions are wrong).
* **404 Not Found**, an api key with *id* not found.

## Resources

### Component Id

A reference to a component using *name* and *revision*.

* **name** a component name,
* **revision** a component version

### Component definition

Provides a component definition. The component is identified by *name* and *revision*.

* **name** a component name,
* **revision** a component version, generated if ommitted,
* **definition** a component definition using [Component DSL](/technical-specification/hub-backend/components#component-dsl).

### Component Configuration Id

A reference to a component configuration

* **name** a component configuration name,
* **version** a component configuration version

### Api key

Api Key resource represents an client api access token with associated rights.

It contains the following fields:

* **name** a name that make sense to a human or a description of the key,
* **apiKey** a token by which the client can authenticate itself to the server,
* **permissions** a list of rights that were given to the api key.
  * **componentId**, [a component id resource](#component-id),
  * **exposed**, optional name of exposed function,
  * **permission**, at this moment only `execute` is supported.
    An example api key resource:

```
{
  "name":"Component token for test-auth-token",
  "apiKey":"1234567890",
  "permissions": [
     { "componentId": { "name":"test-auth-token" }, "permission":"execute" }
  ]
}

```