Customers Management API

A REST-based API is available to manage various parts of the system. The base path for the Management API is {management-api-root}/{ownerId}/management. An example endpoint might look like the following:

https://api.dev.utilihive.io/myCompany/management/flows

Access

Access to the Management API requires a valid OAuth2 JWT Bearer token generated by a user with an Admin or Deployer role. The token is retrieved by making a POST request to {identity-api-root}/authentication/token with the following URL encoded form parameters:

Parameter Description

grant_type

The grant type to use. Must be set to password.

username

The Admin or Deployer user’s username (typically their email address).

password

The user’s password.

scope

The scope of the access request. Must be set to management.

The following curl command demonstrates an example request:

curl -X POST "https://api.dev.utilihive.io/metercloud-integration-identity/api/authentication/token" \
-H  "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password&username=<username>&password=<password>&scope=management"

All future requests will then need to include the returned access_token as a Bearer token. With curl, this would look like the following:

curl "https://api.dev.utilihive.io/myCompany/management/flows" \
-H "Authorization: Bearer <access_token>"

Documentation

The OpenAPI specifications for the entire Management API are available by making an authorized GET request to {management-api-root}/{ownerId}/management/openapi.json. The returned JSON can then be loaded into the online Swagger editor to more easily review the various endpoints and see example request bodies.

Flow APIs

The Flow Management API can create, update, delete, and view flows deployed by the corresponding owner (i.e., the ownerId). The following REST endpoints are available on the base path {management-api-root}/{ownerId}/management:

Method Path Description

GET

/flows

Get flow details for all deployed flows (for the specified owner).

POST

/flows

Create a new flow. See the OpenAPI specs for an example request body.

GET

/flows/flowIds

Get only the flow IDs for all deployed flows.

GET

/flows/{flowId}

Get the details for a single flow.

PUT

/flows/{flowId}

Update a flow. See the OpenAPI specs for an example request body.

DELETE

/flows/{flowId}

Delete an existing flow.

POST

/flows/{flowId}/disable

Disable a flow with a compatible source (e.g., REST sources). Request body must include principalId and reason.

POST

/flows/{flowId}/enable

Enable a disabled flow. Request body must include principalId.
Even though flows can be created with the Management API, it is recommended to use the SDK’s more feature rich Deployer tools.

Resource Registry APIs

The Resource Registry Management API can create, update, delete, and view resources, secrets, and tables deployed by the corresponding owner. Registry related endpoints are available on the base path {management-api-root}/{ownerId}/management/registry.

Resources

The following endpoints are available to manage resources:

Method Path Description

GET

/resource-types

Get all resource types that have been deployed (e.g., OpenAPIv3, WSDLv1, etc.).

GET

/resources

Get all resources deployed for the given ownerId. Filters can be applied via the textQuery and resourceTypes query parameters.

POST

/resources/{type}/{resourceId}

Create a new resource (or revision if resourceId already exists). See the OpenAPI specs for an example request body.

GET

/resources/{type}/{resourceId}/{revision}

Get a specific resource revision.

GET

/resources/{type}/{resourceId}/latest

Get the latest revision of a resource.

DELETE

/resources/{type}/{resourceId}

Delete all revisions of a resource.

Secrets

The following endpoints are available to manage secrets:

Method Path Description

GET

/secrets/generic

Get summaries of all secrets belonging to the ownerId.

GET

/secrets/generic/{key}

Get an individual secret.

PUT

/secrets/generic/{key}

Create or update a secret. See the OpenAPI specs for an example request body.

DELETE

/secrets/generic/{key}

Delete a secret.

PUT

/secrets/{type}/{key}

Create or update a typed secret, where {type} is the kebab-case name of the secret type. For example, type ApiKey would be api-key. Using this endpoint over the generic endpoint provides validation on the typed secret.

Dynamic Tables

The following endpoints are available to manage tables:

Method Path Description

GET

/tables

Get all tables that have been created by the given organization.

GET

/tables/{table}/rows

Get the rows and cells for the given table. See the OpenAPI specs for optional query string parameters.

GET

/tables/{table}/rows/{column}/{value}

Get the full table row by looking up the given column and value.

GET

/tables/{table}/rows/{column}/
{value}/{targetColumn}

Get a single column value from the row that matches the given column and value.

POST

/tables/{table}/rows

Add a new row to the given table (or create the table if it doesn’t exist). See the OpenAPI specs for an example request body.

PATCH

/tables/{table}/rows

Get and optionally add or update the provided row in the table. See the OpenAPI specs for an example request body and auto-create options.

DELETE

/tables/{table}

Delete the given table.

DELETE

/tables/{table}/columns/{column}

Delete the given column from all rows in the table.

DELETE

/tables/{table}/rows/{column}/{value}

Delete the table rows that match the given column and value.

DELETE

/tables/{table}/rows/{column}/
{value}/{targetColumn}

Find the table row that matches the given column/value and delete the cells with the matching target column.