Raw HTTP (Token) Quickstart

Raw HTTP operation allows you to call any endpoint of the underlying service through the Builder UI without having to build individual operations.

This is a simple way to test if you have configured the service correctly and the auth setup is working.

This guide will show you the steps to deploy a token based service connector with a single Raw HTTP operation.

We will be using TMDB (The Movie Database) API as our Token based 3rd party service.

Follow the steps below to achieve this:

Pre-requisite

1. Follow the Introduction to install the CDK and initialize a connector project.
2. You have obtained a namespace . You won't be able to deploy the connector otherwise. To get a namespace , please create a support ticket .

1. Create a service

Services are used by connectors for handling authentications on Tray platform.

Hence if your connector needs a auth (which it does in our TMDB example), you will need a service for it.

Services can be created on the Tray UI. Go to the services tab on the app and click new service:

Now add service details on the page as shown below:

Now save the service. Upon saving, you will see the unique service name.

Copy the unique service name (L3DJ7C5mqVj1yG_tmdb in the screeenshot above). This will be required in the deployment step.

2. Delete the test operation

Connector projects are initialized with a dummy test operation get_post. Delete the get_post operation folder from src directory.

3. Add authentication

Upon initializing the connector, the following two files were created in root of src folder:

1. Auth.ts : This will define the types for auth that is passed with the request.
2. GlobalConfig.ts : This will define the global configs e.g. baseUrl, custom Headers etc. that will remain same with every request.

3.1 Auth.ts

Since TMDB uses token auth, we need to import TokenOperationHandlerAuth from the cdk-dsl

import { TokenOperationHandlerAuth } from "@trayio/cdk-dsl/connector/operation/OperationHandler";

All auth types need to follow a predefined schema as shown here:

export type UserAuth = {
  // user credentials
}

export type AppAuth = {
  // OAuth app credentials
}

export type [ConnectorName]Auth = TokenOperationHandlerAuth<UserAuth, AppAuth>

Since TMDB uses a token auth, we can leave AppAuth blank and token can be added under UserAuth.

Here's the full Auth.ts file for reference:

import { TokenOperationHandlerAuth } from "@trayio/cdk-dsl/connector/operation/OperationHandler";

export type UserAuth = {
  access_token: string // you can call this property anything e.g. token, auth_token etc.
};

export type AppAuth = {};

export type TmdbAuth = TokenOperationHandlerAuth<UserAuth, AppAuth>;

3.2 GlobalConfig.ts

You need to configure the auth in global configs so that it is applied to all operations (including Raw HTTP)

This file uses OperationGlobalConfigHttp to create a Global config object.

The object provides several functions that can be used to add configs, e.g.:

• withBaseUrl function can be used to define a baseUrl .
• withBearerToken can be used to configure a Bearer auth.

Here's the full GlobalConfig.ts file for your reference:

import { OperationGlobalConfigHttp } from "@trayio/cdk-dsl/connector/operation/OperationGlobalConfig";
import { TmdbAuth } from "./TmdbAuth";

export const globalConfigHttp = OperationGlobalConfigHttp.create<TmdbAuth>()
  .withBaseUrl((_ctx) => `https://api.themoviedb.org`)
  /* 
  * Notice how `access_token` is accessed from `auth` below.
  * Name of the property (`access_token` in this case) would depend on what you used in the auth.ts file
  */
  .withBearerToken((ctx) => ctx.auth!.user.access_token);

4. Enabling raw-http

Raw HTTP is enabled by default.

To verify, navigate to the connector.json file in the root of the connector project.

You will find the following line: "rawHttp": {"enabled": true} in the file.

This means, once deployed the connector will have rawHttp operation enabled on the Tray Builder UI.

5. Deploy the connector

The connector is ready to be deployed. Follow the steps as shown on the Deployment API guide.

6. Test on Tray UI

Add the connector to a existing / new workflow.

You can configure the properties panel to call any endpoint from the 3rd party service.

Here is the screenshot of the panel configured to call GET /3/movie/top_rated

Next Steps

You can start building individual operations on the connector now.

We recommend following the Single HTTP quickstart first and then moving to building section.