Chapter 4. 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 4.1, “Exposing Fuse Online public REST APIs for use by external tools”
- Section 4.2, “Description of base URL for Fuse Online public REST API endpoints”
- Section 4.3, “Obtaining a secret token for calling a public REST API endpoint”
- Section 4.4, “How to find integration IDs”
-
Section 4.5, “Format for specifying
curl
commands to invoke Fuse Online public endpoints”
4.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 for each installation of Fuse Online. For Fuse Online environments on the same cluster, while you can use the same service account to expose the public APIs, the recommendation is to use a different service account for each installation for better security.
Prerequisites
- You have an OCP project 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.
- The user who creates the OpenShift public OAuth proxy application must have cluster administration privileges.
Procedure
Create an OpenShift service account that has a name that you specify. For example, the following command creates the
cicd-client
service account:$ oc create serviceaccount cicd-client
Give your new service account permission to access the Fuse Online public API. For example, if
cicd-client
is the name of your new service account, then you would invoke the following command:$ oc policy add-role-to-user edit system:serviceaccount:syndesis:cicd-client
Invoke the following command to create an OpenShift template for exposing Fuse Online public REST API endpoints:
$ oc create -f https://raw.githubusercontent.com/syndesisio/fuse-online-install/1.7.x/resources/syndesis-public-oauth-proxy.yml
NoteIn the template, the name of the resource is
syndesis-public-oauth-proxy
, while the name of the template itself issyndesis-public-oauthproxy
. As you can see, the resource name hyphenatesoauth
andproxy
but the template file name does not.Invoke the following command to create an OpenShift application that runs a Fuse Online public OAuth proxy process:
$ oc new-app --template=syndesis-public-oauthproxy \ -p PUBLIC_API_ROUTE_HOSTNAME=EXTERNAL_HOSTNAME \ -p OPENSHIFT_PROJECT=$(oc project -q) \ -p OPENSHIFT_OAUTH_CLIENT_SECRET=$(oc sa get-token syndesis-oauth-client) \ -p SAR_PROJECT=$(oc project -q)
Replace
EXTERNAL_HOSTNAME
with the public address of your Fuse Online environment. For example, the address might be something likepublic-fuse-online.127.0.0.1.nip.io
.This command uses the
syndesis-public-oauthproxy
template, which you created in the previous step, to create an OAuth proxy process that exposes the Fuse Online public REST API. This OAuth proxy allows external tools to access the Fuse Online public API at a new public network address by using an OpenShift service account token.
Result
External CI/CD tools can use Fuse Online public REST API endpoints to export and import Fuse Online integrations across Fuse Online environments.
Next steps
- 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.
- Configure external tools to call the Fuse Online public REST API endpoints.
4.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:
https://public-syndesis.192.168.64.42.nip.io/api/v1/public
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:
https://public-syndesis.192.168.64.42.nip.io
The second part of the base URL is the same for all Fuse Online environments:
/api/v1/public
The Fuse Online public REST API provides endpoints that operate on three resources:
-
/integrations
are the integrations that are in the Fuse Online environment that is identified in the base URL. -
/connections
are the connections that are in the Fuse Online environment that is identified in the base URL. -
/environments
is the set of environment labels that are in the Fuse Online environment that is identified in the base URL.
4.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.
Prerequisites
- 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.
Procedure
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-client
is 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-client
service 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
Data
section that displaystoken:
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.
Result
In a 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'
Next step
Copy the token from your saved file into a command that calls a public REST API endpoint in the given Fuse Online environment.
4.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 isi-Lauq5ShznJ4LcuWwiwcz
.
4.5. Format for specifying curl
commands to invoke Fuse Online public endpoints
A 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>]
|
Specify |
|
For the export endpoint, 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 |
The following 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 curl
command:
- The URL at the end of the command identifies the Fuse Online environment whose endpoint you are invoking.
-
timer-to-log
indicates that you are marking thetimer-to-log
integration for the specified environments. -
Specification of
test
andstaging
marks thetimer-to-log
integration for those environments.