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 in each OpenShift project in which Fuse Online is installed.

Prerequisites

  • You have an OCP project in which Fuse Online is installed.
  • The oc client 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 grant command. A user who has administrative privileges for the OpenShift project, but not cluster administration privileges, can execute the other commands.

Procedure

  1. 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 grant command, this procedure assumes that a cluster administrator is performing all steps.

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

  3. Grant roles to the syndesis-public-oauthproxy service 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-oauthproxy service account. The ClusterRoleBinding specifies the name of the OpenShift project in which you are exposing the API, which is fuse-online-north in this example:

    • ClusterRole: syndesis-auth-delegator
    • ClusterRoleBinding: syndesis-fuse-online-north-auth-delegator

  4. Create a client service account and grant it permission to access the Fuse Online public API:

    1. Create an OpenShift service account with a name that you choose. For example, the following command creates the cicd-client service account:

      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.

    2. Grant the client service account permission to access the Fuse Online public API. If fuse-online-north is the name of the OpenShift project in which Fuse Online is installed, and if cicd-client is 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`

  5. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis

    2. 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.yml file, 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

    3. Save (or close) the resource.

      Saving the syndesis custom 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 syndesis custom resource, then the public API OAuth proxy service has already been deployed. This is probably because publicApi was enabled and its route specified in the default-cr.yml file that was used to install Fuse Online.

Result

In OpenShift, you can now see:

  • A pod for the syndesis-public-oauthproxy deployment configuration.
  • A syndesis-public-oauthproxy service.
  • A syndesis-public-api route.

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.

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>]

Table 4.1. curl command options

OptionDescription

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