# Restful Services Integration

## Architecture

The concept is simple:

1. Store API credentials in the secret manager (so only authorized people can see them). On GCP, it uses Google Cloud secret manager.
2. Using credentials, retrieve access token. To support, the use of the same token in a clustering environment, store it in a distributed memory cache provided by Trillo Workbench.
3. Use Trillo funciton to write connector logic using HTTP APIs.

<figure><img src="/files/BxPG8sap1HLaFcaipTEE" alt=""><figcaption><p>Integrating with External Restful Services using Trillo Functions as Connectors</p></figcaption></figure>

## Writing Connectors

1. Store client credentials in the secret manager (preferably).
2. Store any other API related configuration as domain meta data.
3. Write function using MetaApi and TokenApi (see below).
4. Use the following HTTPApi method to communicate with the service.&#x20;
5. Test in IDE or on the cloud by copying the code using Trillo Workbench UI.

The following APIs are available using Trillo SDK.

```
public static Result httpGet(String requestUrl, Map<String, String> headers);

public static Result httpPost(String requestUrl, Map<String, Object> body, 
   Map<String, String> headers);

public static Result httpPut(String requestUrl, Map<String, Object> body, 
   Map<String, String> headers);
   
public static Result httpDelete(String requestUrl, Map<String, Object> body, 
   Map<String, String> headers);
```

## API for Retrieving Secret Value from Secret Manager

1. It assumes that an admin (authorized person) has given name to each value and made entry in the GCP secret manager.&#x20;
2. Using the name of a secret you can retrieve its value at runtime using the following API.

```
TokenApi.retrieveSecret(String secretName)
```

## Storing Access Token in Trillo Workbench Distributed Memory Cache

You normally obtain access token once and use it several times. In a clustering environment, one node may fetch the token, but code running on another node uses it due to a later request. The access token should be stored in a distributed memory cache so it is available to processes running on different nodes.

Assuming you receive OAuth2 compliant access token as a JSON object, it can be converted to a Java class OAuth2Token as follows.

```
public static OAuth2Token makeOAuthToken(Map<String, Object> response, 
                                         String serviceName)
                                         
This is a method of TokenApi class.
```

You can then add it to Trillo Workbench distributed cache using the following API call.

```
public static Result addOAuthToken(String key, OAuth2Token token)

This is a method of TokenApi class.
```

You can later retrieve it from the cache using the following API call.

```
public static Result getOAuthToken(String key)

This is a method of TokenApi class.
```

You can remove the token from the cache as follows.

<pre><code><strong>public static Result removeOAuthToken(String key)
</strong>
This is a method of TokenApi class.
</code></pre>

The following method of OAuth2Token can be used to check if the token has expired.

```
public boolean isAccessTokenExpired()

This is a method of OAuth2Token class.
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://trillo.gitbook.io/trillo-workbench/integration-with-external-services.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.