Chapter 5. How to invoke Fuse Online public REST API endpoints
When you are running Fuse Online on OCP, each Fuse Online environment can expose public REST API endpoints. External Continuous Integration/Continuous Delivery (CI/CD) tools can invoke these endpoints to operate on the resources that are in that Fuse Online environment.
In each Fuse Online environment, an OpenShift administrator must expose Fuse Online public REST API endpoints before external tools can invoke those endpoints. The command that invokes an API endpoint specifies the URL for the Fuse Online environment on which the endpoint operates, a secret token, and an authorization token.
See the following topics for details:
- Section 5.1, “Exposing Fuse Online public REST APIs for use by external tools”
- Section 5.2, “Description of base URL for Fuse Online public REST API endpoints”
- Section 5.3, “Obtaining a secret token for calling a public REST API endpoint”
- Section 5.4, “How to find integration IDs”
Section 5.5, “Format for specifying
curlcommands to invoke Fuse Online public endpoints”
5.1. Exposing Fuse Online public REST APIs for use by external tools
When you are running Fuse Online on OCP on-site, you might want to use an external tool to copy Fuse Online integrations from one Fuse Online environment to another Fuse Online environment. An external CI/CD tool might be a Jenkins job, an Ansible playbook, a
cron-based shell script, or something else. For example, an Ansible playbook can export an integration from a Fuse Online development environment and import it into a Fuse Online testing environment.
To enable this, you must expose Fuse Online public REST API endpoints for each Fuse Online environment. In other words, you must repeat the procedure here in each OpenShift project in which Fuse Online is installed.
- You have an OCP project in which Fuse Online is installed.
occlient tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
- You use an external CI/CD tool and you want it to copy marked integrations from one Fuse Online environment to another.
Cluster administration privileges are required to execute the
syndesis-operator grantcommand. A user who has administrative privileges for the OpenShift project, but not cluster administration privileges, can execute the other commands.
Log in to OpenShift with an account that has cluster administration privileges. For example:
oc login -u admin -p admin
While cluster administration privileges are required for only the
syndesis-operator grantcommand, this procedure assumes that a cluster administrator is performing all steps.
Switch to an OpenShift project in which Fuse Online is running. You are exposing the public API in only this project. For example:
oc project fuse-online-north
Grant roles to the
syndesis-public-oauthproxyservice account. Your OpenShift project uses this service account to run an OAuth proxy service. Specify a user account that has cluster administration privileges. For example:
syndesis-operator grant --user developer
This command creates and assigns a cluster role and cluster role binding to the
syndesis-public-oauthproxyservice account. The ClusterRoleBinding specifies the name of the OpenShift project in which you are exposing the API, which is
fuse-online-northin this example:
Create a client service account and grant it permission to access the Fuse Online public API:
Create an OpenShift service account with a name that you choose. For example, the following command creates the
oc create serviceaccount cicd-client
Commands that invoke public API endpoints use this account to access the public API. Also, you will need this service account to obtain a secret token, which must be specified in calls to API endpoints. This is described in Obtaining a secret token for calling a REST API endpoint.
Grant the client service account permission to access the Fuse Online public API. If
fuse-online-northis the name of the OpenShift project in which Fuse Online is installed, and if
cicd-clientis the name of the service account that you created for accessing the API service, then you would invoke the following command:
oc policy add-role-to-user edit system:serviceaccount:fuse-online-north:cicd-client`
Invoke the following command, which typically opens the resource in an editor:
oc edit syndesis
Edit the resource so that it enables the public API and specifies the Fuse Online environment’s public address for invoking endpoints as the setting of
routeHostname. (If edits to the
default-cr.ymlfile, which was used to install Fuse Online, enabled the public API and specified the route hostname for endpoints, you will not need to edit the resource.)
Your cluster setup determines the public address that you need to specify. For details, see the OpenShift documentation for routes. In the following example, the route host name is valid for a minishift cluster.
spec: addons: publicApi: enabled: true routeHostname: public-syndesis.192.168.64.63.nip.io
Save (or close) the resource.
syndesiscustom resource triggers
syndesis-operator, which is responsible for installing Fuse Online, to deploy the public API OAuth proxy service.
If you did not need to edit the
syndesiscustom resource, then the public API OAuth proxy service has already been deployed. This is probably because
publicApiwas enabled and its route specified in the
default-cr.ymlfile that was used to install Fuse Online.
In OpenShift, you can now see:
A pod for the
In the OpenShift project in which you performed this procedure, external CI/CD tools can use Fuse Online public REST API endpoints to export or import Fuse Online integrations.
- Mark integrations for export to other Fuse Online environments. You can mark an integration in the Fuse Online console or invoke the Fuse Online public REST API endpoint that marks an integration.
To confirm that public API endpoints are available, invoke a
curlcommand that returns environment names. See Endpoint for obtaining a list of environment labels.
- Configure external tools to call the Fuse Online public REST API endpoints.
5.2. Description of base URL for Fuse Online public REST API endpoints
The base URL for Fuse Online public REST API endpoints is something like this:
The first part of the base URL is different for each Fuse Online environment. When you create the OpenShift application that runs the Fuse Online public OAuth proxy that enables access to public REST API endpoints, you specify the public address of your Fuse Online environment. This address is the first part of the base URL for calling endpoints that operate in that Fuse Online environment. For example:
The second part of the base URL is the same for all Fuse Online environments:
The Fuse Online public REST API provides endpoints that operate on three resources:
/integrationsare the integrations that are in the Fuse Online environment that is identified in the base URL.
/connectionsare the connections that are in the Fuse Online environment that is identified in the base URL.
/environmentsis the set of environment labels that are in the Fuse Online environment that is identified in the base URL.
5.3. Obtaining a secret token for calling a public REST API endpoint
A command that calls a Fuse Online public REST API endpoint must specify a secret token. This token is for the service account that you created when you exposed the Fuse Online public REST API in a given Fuse Online environment.
- You are running Fuse Online on OCP on-site.
- You exposed the public REST API that is provided by a Fuse Online environment in which you want to invoke endpoints.
Obtain the names of the secret tokens for the service account that you created when you exposed the public REST API for this Fuse Online environment. For example, if
cicd-clientis the name of the service account, you would invoke the following command:
oc describe serviceaccount cicd-client
This displays a list of information about the
cicd-clientservice account including the names of its two tokens, which looks something like this:
Tokens: cicd-client-token-gxb25 cicd-client-token-gxdnv
Display the content of either one of the tokens. For example:
oc describe secret cicd-client-token-gxb25
This displays a list of information, including a
Datasection that displays
token:followed by a long series of random characters. This is one of the service account’s two secret tokens.
- Copy the secret token, paste it into a file, and save it.
curl command, specification of the secret token looks like this:
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA'
Copy the token from your saved file into a command that calls a public REST API endpoint in the given Fuse Online environment.
5.4. How to find integration IDs
In a command that invokes a Fuse Online public REST API endpoint that operates on only a particular integration, you must specify the ID of the integration that you want the endpoint to operate on. Specify one of the following:
The integration’s name
You must specify it exactly as it appears in the Fuse Online console, for example,
timer-to-log. If the integration name has any spaces or special characters, then you must specify HTML escape characters.
The internal integration ID
This ID is in the Fuse Online console URL when you view an integration’s summary. To view an integration’s summary, in the left navigation panel, click Integrations. In the list of integrations, click the entry for the integration whose ID you need.
With the integration summary visible in the browser, you would see something like this at the end of the URL:
/integrations/i-Lauq5ShznJ4LcuWwiwcz. This integration’s ID is
5.5. Format for specifying
curl commands to invoke Fuse Online public endpoints
curl command that calls a Fuse Online public REST API endpoint has the following format:
curl [options] \ -H "Content-Type: <media-type>" \ -H "SYNDESIS-XSRF-TOKEN: awesome" \ -H `Authorization: Bearer <token>` \ <base-url><endpoint> \ [--request <HTTP-method>] \ [-d <data>] \ [-o <filename>]
curl command options
| || |
| || |
For the export and import endpoints, specify
| || |
Specify a secret token for the OpenShift service account that you created when you exposed the public REST API.
| || |
Specify the base URL for the Fuse Online environment that has the integration, connection, or environment label, that you want the endpoint to operate on.
| || |
Specify the endpoint that you want to call.
| || |
Optionally, specify the HTTP method, for example,
| || |
Optionally, depending on the endpoint that is being called, specify arguments that the endpoint requires. For example, to change an integration’s environment label to
| || |
Optionally, if you need to specify the name of a file that contains output, specify the
curl command invokes the Fuse Online public API endpoint that marks an integration for one or more environments that you specify:
curl -v -k -L -H "Content-Type: application/json" -H "SYNDESIS-XSRF-TOKEN: awesome" -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA' https://public-syndesis.192.168.64.42.nip.io/api/v1/public/integrations/timer-to-log/tags -d '["test","staging"]' --request PUT
In the sample
- The URL at the end of the command identifies the Fuse Online environment whose endpoint you are invoking.
timer-to-logindicates that you are marking the
timer-to-logintegration for the specified environments.
timer-to-logintegration for those environments.