Orchestration API

The orchestration module provides a number of API endpoints that are all protected by either basic auth or a session cookie. The authenticated user must have the use orchestration permission.

External orchestration clients can use these endpoints to interact with the orchestration module.

Endpoints

Get a list of available services

• Path: /orchestration/services
• Method: GET

Returns a list of all available services sorted by their labels. Each service comes with 4 properties:

• id: The service ID.
• label: The service label.
• description: The service description.
• config: The service configuration items, each of which an array with 9 properties:
  • key: The configuration item key.
  • label: The configuration item label.
  • description: The configuration item description.
  • required: Whether the configuration item is required.
  • type: The configuration item type, e.g. string, boolean, integer, etc.
  • editable: Whether the configuration item is editable.
  • default_value: The default value.
  • weight: The configuration item weight.
  • options: The configuration item options, each of which an array with 2 properties:
    • key: The option key.
    • name: The option name.

Execute a service

• Path: /orchestration/service/execute
• Method: POST
• Body: A JSON string containing the following properties:
  • id: The service ID.
  • config: The service configuration as key-value pairs.

Returns the data returned by the service. If there is an exception, the response will be a JSON string containing the error property with the exception message and the response code will be 500.

Register a webhook

• Path: /orchestration/webhook/register
• Method: POST
• Body: A JSON string containing the following properties:
  • id: The webhook ID.
  • webHookUrl: The webhook URL.

Returns the same JSON string that it received with a response code 200.

Unregister a webhook

• Path: /orchestration/webhook/unregister
• Method: POST
• Body: A JSON string containing the following properties:
  • id: The webhook ID.

Returns the same JSON string that it received with a response code 200.

Poll for changes

• Path: /orchestration/poll
• Method: POST
• Body: A JSON string containing the following properties:
  • name: The name identifying the poll.
  • timestamp: The last time the poll was executed, in epoch seconds.
  • id: The last received item ID that the poll has received.

Note: the poll supports 2 alternatives modes, either time based or ID based. Therefore, the request body should only contain the timestamp OR the ID, not both. Should there be both, timestamp takes precedence. If neither is provided, the response will be a JSON string containing the error property with the error message and the response code will be 400.

Returns a list of all available items that either match the time based or ID based criteria. Each item comes with 2 properties:

• data: The item data. The exact format depends on the service that generated the item.`
• timestamp: The item timestamp, in epoch seconds.
• id: The item ID.

Again, the item response either contains the timestamp or the ID, not both.