Guides

Admin API

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

Suggest Edits

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.

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.
  • 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
Response:
  • 201 Created, a success response with a reference to a newly registered component:
    • /api/components/{name} as a Location header,
    • 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 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:

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

The corresponding response can be one of the following:

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 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 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.

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,
    • 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" }
  ]
}

Updated 4 months ago