HTTP: Using the HTTP adapter

Advanced tutorial (coding knowledge required)

Note: The HTTP adapter is split into two connectors - Basic and OAuth2.

HTTP Connector

Authentication

Different applications support different authentication structures.

Workato enables you to communicate with various apps by handling the authentication portion of a request in the connections section. HTTP and HTTP (OAuth2) have different approaches to authentication.

HTTP Basic

None

No authentication is required. You may skip the 'connection' portion.

Basic

Typically, a basic authentication requires a username and password combination when making requests, which is encoded with Base64 in transit.

Some APIs use a variation of the standard Basic access authentication. For example, Close.io API expects an API Key generated in the individual User’s account. It should be used as a username with a blank password in the standard basic authentication format.

Header Auth

Header Authentication can be used when you have a generated token ready for use. All you'll need to do is add this token to the Header authorization field with the appropriate key name.

Query Params

This connection type is useful when the authentication structure is based on validating an API key as a parameter. What you need to do is to add the parameter key/value pair in the params authorization field and you are good to go.

Custom

If the API you intend to connect to does not follow any of the conventional authentication structure, fret not!

We provide custom type authentication for that reason. It includes all typical fields and components of connections available in all the previous types. You can adjust the appropriate fields to suit the desired application authentication structure.

HTTP OAuth2 Connector

For a more secure method of authentication, we recommend using OAuth 2.0. It is an open standard and is generally a more secure way for users to log into third party websites without exposing their credentials.

The HTTP (OAuth2) connector supports the authorization code grant variant of the OAuth2 standard.

Required components in OAuth 2.0 type connection:

1. Authorization_url

2. Token_url

3. Client_id and client_secret

4. Credentials

Redirect URI will be appended to the authorization request by the framework, so there is no need to include it. If the application requires that you register the redirect URI beforehand, use: https://www.workato.com/oauth/callback

Some APIs require that you include certain parameters in the authorization URL. Common examples are response_type (“code” or “token”) and scope (“read”, “write”, “admin”, etc).

HTTP Action

A HTTP Action is a REST request to a Application API endpoint. It is executed during a run of the recipe.

Method

Available methods:

• GET
  
• POST
  
• PUT
  
• DELETE
  
• HEAD
  
• PUT
  

URL

Endpoint URL of the REST request.

Headers

Additional HTTP request Headers. If there is a constant HTTP request Headers for each REST Request, consider moving this component to the Authentication portion.

Body

Payload attached to the REST request. Can be in XML or JSON Format

Output type

Available Choices:

• Raw HTTP response body
  
• Parse response as JSON
  
• Parse response as XML
  

Sample Output

Define your sample output (format should abide by the output type defined earlier) This sample output is crucial because it defines a schema for the action. The schema is then used as data pills for mapping (refer to the right side of the image for example of a sample output from a previous step)

HTTP Trigger

Webhook

Event Name

This name is an identifier for your dedicated webhook endpoint. Input here will change the webhook URL show at the top of the trigger. This Webhook URL is used to pick up real-time events posted from webhook events from your application.

Note: Some APIs require that you “register” or “subscribe” to a webhook subscription before events can be posted to this endpoint.

Webhook Type

• Get request
  
• PUT/POST with JSON Payload
  
• PUT/POST with XML Payload
  
• PUT/POST with FORM encoded Payload
  

Event Schema

Similar to sample output (above), this component defines the schema of the trigger. It allows you to use the data from the output of a trigger event in the form of a data pill. Make sure that the format is identical to the actual output data, if not, the data pills used in subsequent steps will not behave as expected.