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:

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

  1. 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

  2. Give your new service account permission to access the Fuse Online public API. For example, if syndesis is the name of the OpenShift project in which Fuse Online is installed, and i 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

  3. 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/syndesis/1.8.x/install/support/syndesis-public-oauth-proxy.yml
    Note

    In the template, the name of the resource is syndesis-public-oauth-proxy, while the name of the template itself is syndesis-public-oauthproxy. As you can see, the resource name hyphenates oauth and proxy but the template file name does not.

  4. Invoke the following command to create an OpenShift application that runs a Fuse Online public OAuth proxy process.

    For OpenShift Container Platform 4.2, also specify -p OAUTH_PROXY_TAG=4.2. 

    $ 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 like public-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

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

  1. 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

  2. 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 displays token: followed by a long series of random characters. This is one of the service account’s two secret tokens.

  3. 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 is i-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>]

[options]

Specify curl options that you choose.

<media-type>

For the export and import endpoints, specify multipart/form-data. For all other endpoints, specify application/json.

<token>

Specify a secret token for the OpenShift service account that you created when you exposed the public REST API.

<base-url>

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.

<endpoint>

Specify the endpoint that you want to call.

[--request <HTTP-method>]

Optionally, specify the HTTP method, for example, --request POST.

[-d <data>]

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 test, you would specify -d `test`

[-o <filename>]

Optionally, if you need to specify the name of a file that contains output, specify the -o curl option with the name of a file, for example, -o export.zip.

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 the timer-to-log integration for the specified environments.
  • Specification of test and staging marks the timer-to-log integration for those environments.