Create an API recipe ​

This guide explains how to create an API recipe. External business partners and internal stakeholders can use this endpoint to access and consume data without requiring access to a Workato account.

Refer to the Add users to Google Workspace use case for steps to create an integration for Workato API platform and Google Workspace that enables you to add users to your Google Workspace with your preferred CLI or when a new employee is detected in BambooHR.

Supported data types ​

Use the Content type drop-down menu to configure the data format the connector accepts. API recipes support the following options:

• JSON: Accepts data in JavaScript Object Notation format. Use this for most REST APIs and structured payloads.
• Text/XML: Accepts raw content such as XML, SOAP, CSV, and YAML. Use this to handle non-JSON formats or plain text payloads.
• Multipart: Accepts requests in multiple parts. Use this for requests that include mixed data.

Refer to Parse the request body for additional data processing information.

Top-level array support ​

The Request structure and Response structure drop-down menus control the outermost shape of the request or response body with a single object or a top-level array.

• Object: Use this option if you need the body to nest an array under a key, for example:

  json

  {
    "accounts": [
      { "id": 1, "name": "Acme Corp" },
      { "id": 2, "name": "Globex Inc" }
    ]
  }

• Array of objects, Array of strings, Array of integers, Array of numbers, Array of booleans, Array of dates, or Array of date-times: Use one of these options if you need the body to be a bare top-level array, for example:

  json

  [
    { "id": 1, "name": "Acme Corp" },
    { "id": 2, "name": "Globex Inc" }
  ]

The Request body and Response schema sections only appear when the structure is set to Object or Array of objects, because the other array types hold scalar values and don't have a schema to define. The selected structure defines the type of each item for an array type.

New endpoints default to Object, and existing endpoints behave as they did before. Top-level arrays also work when you import or export a specification in OpenAPI 3 or Swagger 2 format.

The Request parameters output group includes List size and List index datapills so you can loop over the request body's items when you set Request structure to an array type.

Request body and legacy request schema ​

The trigger's Request section defines path parameters, query parameters, and the request body in separate sections. Previously, query parameters were part of the request schema. You can still define query parameters in the request body. If the same field appears in more than one place, path parameters take precedence over query parameters, and query parameters take precedence over the request body.

Existing endpoints keep their saved Request schema field, which is now a legacy field. The Request schema field remains fully supported, and the datapills it generates continue to resolve in your recipe. Workato doesn't migrate existing endpoints, and refreshing the schema doesn't change them. New endpoints use the Request body field instead. The Response section doesn't have a legacy field. Use Response structure to select the shape of the response.

Migrate to the Request body field ​

You can keep using the legacy Request schema field. Complete the following steps if you prefer to move an existing endpoint to the Request body field:

Create the recipe ​

Complete the following steps to create an API recipe:

[
  {
    "name": "ID",
    "type": "string",
    "optional": false,
    "control_type": "text",
    "label": "ID",
    "hint": "Account ID"
  },
  {
    "name": "Name",
    "type": "string",
    "optional": false,
    "control_type": "text",
    "label": "Name",
    "hint": "Account name"
  }
]

Your API recipe is ready to test and implement.

A configured API recipe

Parse the request body ​

Optionally, you can use Workato's data handling connectors to create datapills from data an endpoint receives.

Complete the following steps to parse a request body:

The data parsing step is complete. Workato generates datapills based on the structure defined in the Sample document field.

Expose an API endpoint ​

After you create the recipe, the next step is to expose the API recipe as an endpoint in the API platform. This allows you to test the endpoint before releasing it to production and ensure it behaves as expected.

Complete the following steps to expose the recipe as an endpoint:

Endpoint management ​

You can manage an API endpoint using the following tools:

• API recipe collections organize endpoints into groups for distribution and version control.
• API clients organize users into groups for API access management.
• API keys provide secure authentication for API clients.
• API access policies enforce rate limits and request quotas for clients.
• The RecipeOps connector enables you to build recipes to monitor and manage workspaces. For example, you can use the API concurrency threshold exceeded trigger to monitor the concurrency quota in a workspace.