Chapter 6. Fuse Online public REST API endpoints reference

This section provides reference information for each Fuse Online public REST API endpoint. For additional information, see How to invoke Fuse Online public REST API endpoints.

The OpenAPI document that defines the public REST API endpoints is available in your Fuse Online environment at https://<fuse-online-host>/api/v1/openapi.json. However, this document defines the tags object as having three tags: public-api, extensions, and integration-support. Only the public-api tag is accessible when using the OpenShift public OAuth proxy process for Fuse Online. You should ignore the other two tags.

6.1. Endpoint for obtaining the state of an integration

This endpoint returns the state of the specified integration. The state is Running, Stopped, Pending, or Error.

Method and endpoint

GET

/public/integrations/{id}/state

Table 6.1. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required path parameter. Name or internal ID of the integration whose state you want to obtain. See How to find integration IDs.

Request example

In the following example, the endpoint returns the state of the timer-to-log integration:

/public/integrations/timer-to-log/state

Produces

application/json

Response example

{"currentState":"Unpublished","stateDetails":{"id":"i-Lc0JLrsUFtBJfR_ylfEz:5","integrationId":"i-Lc0JLrsUFtBJfR_ylfEz","deploymentVersion":5,"detailedState":{"value":"BUILDING","currentStep":2,"totalSteps":4},"namespace":"syndesis","podName":"i-timer-to-log-5-build","linkType":"LOGS"}}`

6.2. Endpoint for obtaining a list of an integration’s environment labels

This endpoint returns the environment labels (tags) that have been applied to the specified integration.

Method and endpoint

GET

/public/integrations/{id}/tags

Table 6.2. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required path parameter. Name or internal ID of the integration whose environment labels you want to obtain. How to find integration IDs.

Request example

In the following example, the endpoint returns the environment labels for the timer-to-log integration:

/public/integrations/timer-to-log/tags

Produces

application/json

Response example

{"test":{"name":"test","releaseTag":"i-Lc5WI16UFtBJfR_ylggz","lastTaggedAt":1554887553159,"lastExportedAt":1554887330152,"lastImportedAt":1554888047271},"staging":{"name":"staging","releaseTag":"i-Lc5WI16UFtBJfR_ylgfz","lastTaggedAt":1554887553159}}

6.3. Endpoint for marking an integration and keeping unspecified tags

This endpoint uses the PATCH method to mark the specified integration for the specified environment(s). If the integration is already marked for a specified environment, the endpoint updates the timestamp for that environment label. If the integration was previously marked for an environment that is not specified in a new request, the endpoint leaves that tag in place and does not update its timestamp.

This PATCH endpoint is a convenience method for CI/CD tools because it adds tags without the need to remove any other existing tags. This is in contrast to the PUT endpoint, which marks the integration for specified environments and removes any tags for environments that are not specified in the request.

Method and endpoint

PATCH

/public/integrations/{id}/tags

Table 6.3. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Name or internal ID of the integration that you want to mark for the specified environment(s). See How to find integration IDs.

Additional Parameters

--request PATCH

 

Specify the PATCH method.

-d [env{,…​}]

string

Required. Specify one or more, comma-separated, environment labels, that you want to add to the specified integration. You must have already created the environment label; the endpoint cannot create a label. See Marking integrations for CI/CD.

Request example

In the following example, the endpoint marks the timer-to-log integration for the test2 and test3 environments:

public/integrations/timer-to-log/tags --request PATCH -d '["test2","test3"]'

Produces

application/json

Response example

{"test2":{"name":"test2","releaseTag":"i-LcXydouUFtBJfR_ylgrz","lastTaggedAt":1555365010746},"test3":{"name":"test3","releaseTag":"i-LcXydouUFtBJfR_ylgsz","lastTaggedAt":1555365010746},"test":{"name":"test","releaseTag":"i-Lc5WI16UFtBJfR_ylggz","lastTaggedAt":1554887553159,"lastExportedAt":1554887330152,"lastImportedAt":1554888047271},"staging":{"name":"staging","releaseTag":"i-Lc5WI16UFtBJfR_ylgfz","lastTaggedAt":1554887553159}}

6.4. Endpoint for marking an integration and removing unspecified tags

This endpoint uses the PUT method to mark the specified integration for the specified environment(s). If the integration was previously marked for an environment that is not specified in the new request, the endpoint removes that environment label from the integration.

To mark an integration without removing unspecified environment labels, call the PATCH method endpoint instead.

Method and endpoint

PUT

/public/integrations/{id}/tags

Table 6.4. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Name or internal ID of the integration that you want to mark. See How to find integration IDs.

Additional Parameters

--request PUT

 

Specify the PUT method.

-d [env{,…​}]

string

Required. Specify one or more, comma-separated, environment labels. The endpoint marks the specified integration for these environments. You must have already created the environment label; the endpoint cannot create a label. See Marking integrations for CI/CD.

Request example

In the following example, the endpoint marks the timer-to-log integration for the test2 and test3 environments. If the integration was previously marked for any other environments, the endpoint removes those tags from the integration.

public/integrations/timer-to-log/tags --request PUT -d '["test2","test3"]'

Produces

application/json

Response example

{"test2":{"name":"test2","releaseTag":"i-LcXyw7GUFtBJfR_ylgtz","lastTaggedAt":1555365085713},"test3":{"name":"test3","releaseTag":"i-LcXyw7GUFtBJfR_ylguz","lastTaggedAt":1555365085713}}

6.5. Endpoint for publishing an integration

This endpoint publishes the specified integration. If the integration is already running, then the endpoint stops the integration and re-publishes it.

Method and endpoint

POST

/public/integrations/{id}/deployments

Table 6.5. Parameters

NameTypeDescription

Required Header Parameter

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameters

{id}

string

Required. Name or internal ID of the integration that you want to publish. See How to find integration IDs.

Request example

In the following example, the endpoint publishes the timer-to-log integration.

/public/integrations/timer-to-log/deployments

Produces

application/json

Response example

In this example, the ellipsis indicates the omission of some of the response.

{"id":"i-Lc0JLrsUFtBJfR_ylfEz:8","version":8,"createdAt":1555365135324,"updatedAt":1555365135324,"userId":"system:serviceaccount:syndesis:syndesis-cd-client","currentState":"Pending","targetState":"Published","integrationId":"i-Lc0JLrsUFtBJfR_ylfEz", . .2c+PC9zdmc+","description":"Trigger events based on an interval or a cron expression","isDerived":false},"stepKind":"endpoint"},{"id":"-Lc0I7wqEVfKCDDHC8Jv","configuredProperties":{"bodyLoggingEnabled":"true","contextLoggingEnabled":"true"},"metadata":{"configured":"true"},"stepKind":"log","name":"Log"}]}],"continuousDeliveryState":{"test2":{"name":"test2","releaseTag":"i-LcXyw7GUFtBJfR_ylgtz","lastTaggedAt":1555365085713},"test3":{"name":"test3","releaseTag":"i-LcXyw7GUFtBJfR_ylguz","lastTaggedAt":1555365085713}}}}

6.6. Endpoint for stopping an integration

This endpoint stops the specified integration.

Method and endpoint

PUT

/public/integrations/{id}/deployments/stop

Table 6.6. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Name or internal ID of the integration that you want to stop. See How to find integration IDs.

Request example

In the following example, the endpoint stops the timer-to-log integration.

/public/integrations/timer-to-log/deployments stop

Produces

application/json

Response example

No content with a 204 status code

6.7. Endpoint for exporting integrations

This endpoint exports integrations. The default behavior is that the endpoint exports integrations that are marked for the specified environment and that have never been exported or that have not been exported since the last time that they were marked for that environment. You can specify options when you want to do either of the following:

  • Export all integrations in a Fuse Online environment and tag them with the specified environment label.
  • Export all integrations that are tagged with the specified environment label regardless of whether or not an integration was updated and tagged since the last time it was exported.

See also: Invoking the Fuse Online public API export endpoint.

Method and endpoint

GET

/public/integrations/{env}/export.zip

Table 6.7. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

multipart/form-data

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you created in the Fuse Online console. The endpoint exports the integrations that are marked for this environment.

Query Parameters

all=true

string

Optional. Specify this option to export all integrations that are in the Fuse Online environment. The endpoint exports the current version of each integration. If an integration is not already marked for the specified environment, then the endpoint adds the specified environment label to the integration. You must have already created the environment label; the endpoint cannot create a label.

ignoreTimestamp=true

string

Export all integrations tagged with the specified environment label. Do this regardless of whether or not an integration was edited and tagged since the last time the integration was exported.

Additional Parameter

-o export.zip

string

Required if you specify the query parameter. Without this option, the exported integrations are in a file named export.zip?all=true.

Request examples

In the first example, the endpoint exports integrations that have been marked for the test1 environment and that have never been exported or that have not been exported since the last time that they were marked for that environment.

/public/integrations/test1/export.zip

In the next example, the endpoint exports all integrations that have been marked for the test1 environment. It does not matter whether or not the integration was updated since the last time it was exported.

/public/integrations/test1/export.zip?ignoreTimestamp=true -o export.zip

In the last example, the endpoint ensures that each integration is marked for the test1 environment and returns all integrations in the export.zip file.

/public/integrations/test1/export.zip?all=true -o export.zip

Produces

application/octet-stream

Response

The export.zip file that contains the exported integration(s). The endpoint returns an HTTP status of 204 if there are no integrations to export.

6.8. Endpoint for importing integrations

This endpoint imports the integrations that are in the provided file. See also: Invoking the Fuse Online public REST API import endpoint.

Method and endpoint

POST

/public/integrations

Table 6.8. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

multipart/form-data

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Additional Parameters

data=@export.zip

string

Required. This is the file that contains the integrations that you want to import. You must have previously invoked the export endpoint to obtain this file.

environment={env}

string

Required. Environment label that you want to add to each imported integration. You must have already created the environment label; the endpoint cannot create a label.

Request example

In the following example, the endpoint imports the integrations that are in the export.zip file and marks them for the testing environment.

/public/integrations -F data=@export.zip -F environment=testing --request POST

Produces

multipart/form-data

Response example

The response is a list of the imported resources, which includes integrations and connections. In the following example, an ellipsis indicates that part of the response is omitted here.

{"lastImportedAt":1554888047271,"results":[{"id":"i-Lc0JLrsUFtBJfR_ylfEz","version":5,"createdAt":1554800274935,"updatedAt":0,"tags":["timer"],"name":"timer-to-log","flows":[{"id":"-Lc0I5AZEVfKCDDHC8Jv","steps":[{"id":"-Lc0I5jnEVfKCDDHC8Jv","configuredProperties":{"period":"900000"},"metadata":…​"description":"Trigger events based on an interval or a cron expression","isDerived":false},"stepKind":"endpoint"},{"id":"-Lc0I7wqEVfKCDDHC8Jv","configuredProperties":{"bodyLoggingEnabled":"true","contextLoggingEnabled":"true"},"metadata":{"configured":"true"},"stepKind":"log","name":"Log"}]}],"continuousDeliveryState":{"staging":{"name":"staging","releaseTag":"i-Lc5WI16UFtBJfR_ylgfz","lastTaggedAt":1554887553159},"test":{"name":"test","releaseTag":"i-Lc5WI16UFtBJfR_ylggz","lastTaggedAt":1554887553159,"lastExportedAt":1554887330152,"lastImportedAt":1554887859824}}}]}

6.9. Endpoint for removing an environment label from a particular integration

This endpoint removes the specified environment label from the specified integration. The environment label itself continues to exist but it no longer marks the specified integration.

Method and endpoint

DELETE

/public/integrations/{id}/tags/{env}

Table 6.9. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameters

{id}

string

Required path parameter. Name or internal ID of the integration that you want to unmark. See How to find integration IDs.

{env}

string

Required path parameter. Environment label that you want to remove from the specified integration.

Additional Parameter

--request DELETE

 

Specify the DELETE method.

Request example

In the following example, the endpoint removes the dev1 environment label from the timer-to-log integration.

/public/integrations/timer-to-log/tags/dev1 --request DELETE

Response example

No content with a 204 status code

6.10. Endpoint for creating an environment label

This endpoint creates an environment label. No integrations are marked with this label until you explicitly mark them in the Fuse Online console or by invoking a public API endpoint.

Method and endpoint

POST

/public/environments/{env}

Table 6.10. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you want to create.

Produces

Does not produce anything but responds as follows:

ResponseDescription

204 No Content

Success.

400 Bad Request

The environment name you specified already exists.

5xx errors

The server is unable to fulfill the request.

Request example

In the following example, the endpoint creates the dev1 environment label:

/public/environments/dev1 --request POST

The dev1 environment label now exists in the Fuse Online environment in which you invoked this endpoint. There are not yet any integrations that are marked with this label.

Response example

No content with response status code 204

6.11. Endpoint for obtaining a list of environment labels

This endpoint returns a list of environment labels that exist in the Fuse Online environment. You create environment labels in the Fuse Online console. See Managing environment labels for CI/CD.

Method and endpoint

GET

/public/environments[?withUses=true]

Table 6.11. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

withUses

Boolean

Optional. If the command specifies withUses=true, the endpoint returns environment labels and the number of integrations that are marked with that label. If not specified, or set to false, the endpoint returns only environment labels.

Produces

application/json

Request examples

  • /public/environments

    Response example:
    ["env-label-1", "env-label-2"]

  • /public/environments/?withUses=true

    Response example
    [{"name":"env-label-1","uses":1},
    {"name":"env-label-2","uses":0}]

6.12. Endpoint for changing an environment label

This endpoint changes an environment label. Integrations that were marked for the original environment label are now marked for the new environment label.

Method and endpoint

PUT

/public/environments/{env}

Table 6.12. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you want to change.

Additional Parameters

-d {env}

string

Required. Specify the new label for the environment. You must have already created the environment label; the endpoint cannot create a label.

--request PUT

 

Specify the PUT method.

Request example

In the following example, the endpoint changes the dev1 environment label to dev2:

/public/environments/dev1 -d ‘dev2’ --request PUT

Integrations that were marked for the dev1 environment no longer have that tag. Those integrations are now marked for the dev2 environment.

Response example

No content with response status code 204

6.13. Endpoint for removing an environment label from all integrations

This endpoint removes the specified environment label from each integration to which it has been applied.

Method and endpoint

DELETE

/public/environments/{env}

Table 6.13. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you want to remove from integrations that have it.

Additional Parameter

--request DELETE

 

Specify the DELETE method.

Request example

In the following example, the endpoint removes the dev1 tag from any integrations that have it:

/public/environments/dev1 --request DELETE

Response example

No content with response status code 204

6.14. Endpoint for changing a connection’s properties

This endpoint changes the properties of the specified connection. This is often useful after you import an integration that has connections that require configuration. For example, you might need to change the credentials that a connection uses.

Method and endpoint

POST

​/public​/connections​/{id}​/properties

Table 6.14. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Replace {id} with the ID of the connection whose properties you want to change. For the connection ID, specify one of the following:

  • The connection’s name, for example: PostgresDB. If the connection name has any spaces or special characters, then you must specify HTML escape characters.
  • The internal connection ID, which is in the Fuse Online console URL when you view a connection’s details. To view a connection’s details, in the left navigation panel, click Connections. Then click the connection whose details you want to view. When the connection details are visible in the browser, you would see something like this at the end of the URL: /connections/i-LaupI8XznJ4LcuWwiwaz. This connection’s ID is i-LaupI8XznJ4LcuWwiwaz.

Request example

The following example changes the properties of the PostgresDB connection. The new value of the user property is myuser, and the new value of the password property is mypassword:

/public/connections/PostgresDB/properties --request POST -d '{ "user": "myuser", "password": "mypassword" }'

Produces

application/json

Sample response

In this example, there is an ellipsis that indicates the omission of a large part of the response.

{"uses":0,"id":"i-LaOziUGpQE45nua4pfCz","name":"TODO app","configuredProperties":{"password":"»ENC:c2cb731046372a275b76beabc92aefa061f79b43fb791fb599d9e85ec0235a7e","basePath":"/api","host":"http://todo-syndesis.my-minishift.syndesis.io/","specification":…​"userId":"admin","lastUpdated":1555365796629,"createdDate":1553066813379,"board":{"id":"i-Lbj4-vqUFtBJfR_ylfCz","metadata":{"connector-id":"i-LaOzcPZpQE45nua4pfBz","connector-version-latest":"1","connector-version-connection":"1"},"messages":[{"level":"WARN","code":"SYNDESIS007"}],"createdAt":1554494263030,"updatedAt":1554494263727,"targetResourceId":"i-LaOziUGpQE45nua4pfCz","notices":0,"warnings":1,"errors":0},"isDerived":false}