API Recipes - Configuring Endpoints To Handle Raw Content

USING CALLABLE RECIPES?

This guide is also applicable to Callable recipes set up as API endpoints.

Note: Callable recipes have been deprecated. They'll continue to function, but you won't be able to create new callable recipes. This guide uses the API platform connector, which functions exactly like the API functionality in callable recipes.

With the API Platform, you can configure your API recipes to accept raw content. This allows you to integrate more data types into your workflow, such as XML/SOAP.

This guide demonstrates how to create an API endpoint that accepts raw content.

Prerequisites

To follow the steps in this guide, you must have:

• Access to the API platform feature. This is an add-on feature. Contact your Workato Customer Success Manager for more info.
• API platform privileges.

Step 1: Create An API Recipe

1

Sign into your Workato account.

2

Create a new recipe using the Build an API endpoint starting option. This creates a recipe with the API Platform - New API request trigger.

3

Go to the trigger's Request section and select text/plain for the Content type. This allows the endpoint to accept any data type sent to it.

4

Configure the trigger's Response:

1

Go to Content type and select text/plain.

2

Go to the Responses section and add the responses with which the endpoint can respond. For example, a Success response can respond with a 200 - OK HTTP status code.

3

Optional. Add a nested schema response to the Response schema section if you plan for your endpoint to return a complex response. You can create a nested schema by dragging and dropping the properties between parents, including the root. Alternatively, click the Edit schema button and provide the nested schema you plan to use.

Add a nested schema

Nested schema example

[
  {
    "name": "Accounts",
    "type": "array",
    "of": "object",
    "label": "Accounts",
    "optional": false,
    "hint": "Found Salesforce accounts",
    "properties": [
      {
        "control_type": "text",
        "label": "ID",
        "name": "ID",
        "type": "string",
        "optional": false,
        "hint": "Account ID"
      },
      {
        "control_type": "text",
        "label": "Name",
        "name": "Name",
        "type": "string",
        "optional": false,
        "hint": "Account name"
      }
    ]
  }
]

5

Define other parameters for the endpoint as required.

---

Step 2: Parse The Request Body

THIS STEP IS OPTIONAL

If you don't plan to use data received by the endpoint as datapills, skip to Step 3.

If you plan to use data received by the endpoint as individual datapills, you can use Workato's data parsers. While Workato supports JSON parsing, it also supports CSV, XML, and YAML.

For example: Our endpoint receives XML content, including a fileId property. We want to use the fileId to retrieve a file from Google Drive. Using the XML tools connector's parse XML action, we can parse the request body and convert the data into datapills we can use in subsequent steps.

1

Add an action step to the recipe, selecting the required parser as the App. In our example, that's the XML tools connector's parse XML action.

2

Provide a Sample document in the action's input.

3

Go to the action's Document field and add the Request body (raw) datapill from the trigger's output.

---

Step 3: Define Response Bodies

In this step, you must define response bodies for the responses you created in Step 1.

Note: If your endpoint has multiple responses, you must repeat the steps in this section for each response type.

1

Add the API platform - Response to API request action as a recipe step.

2

Use the Response menu to select the response you created in Step 1.

3

Go to the Body field and add the data you plan for the endpoint to return in the response body.

---

Step 4: Create An API Platform Endpoint

The last step is to expose the API recipe as an endpoint in the API platform. This allows you to test it before releasing it to production, ensuring it behaves as expected.

1

Navigate to API platform > API collections.

2

Create a new API collection if you don't have an existing collection in your workspace.

3

Follow the steps in the Configuring a new API endpoint guide to add the recipe as an endpoint.

You can now test the endpoint with raw content.

Test REST endpoints with raw content