Skip to Content

Expose an operation as a REST API in Jitterbit Studio

Introduction

API Manager lets you publish a Studio operation as an HTTP endpoint that any authorized caller can invoke on demand. Once published, the endpoint accepts an HTTP request, runs the linked operation synchronously, and returns the operation's output as the HTTP response.

This pattern is useful when an external system or internal tool needs to request data or trigger processing on demand, for example a web application that queries customer records, a partner system that submits orders for processing, or an internal dashboard that triggers a report generation.

This guide uses Studio's built-in Publish as an API option, which opens the API configuration directly from the operation. Alternatively, the same result can be achieved from the API Manager UI (see Custom API).

This guide assumes the following:

  • A custom API is configured and published in API Manager in the same environment as the project.
  • The operation to be exposed as an API is already built and deployed.

For the complementary pattern (receiving event-driven webhook pushes from external systems), see Trigger a Studio operation from a webhook.

Design pattern

flowchart LR A[API client] -->|HTTP request| B[API Manager custom API] --> C[Studio operation] -->|HTTP response| A

Part 1: Publish the operation as an API

Step 1: Open the API configuration

  1. On the design canvas, locate the operation to publish.

  2. Click the actions menu icon on the operation and select Publish as an API.

    The API configuration drawer opens along the bottom of the project designer.

    Note

    This option is only available if the operation has no undeployed changes. Deploy the operation first if the option is unavailable.

Step 2: Configure the API profile

On the Profile step, enter the basic API details:

  1. API Name: Enter a name for internal identification (for example, Customer Query API). This name appears in API Manager and in operation logs.

  2. Service Root: Enter the base path segment used in the public endpoint URL (for example, customers). This field is pre-filled with the operation name in camel case. Spaces are not allowed.

  3. Version number: Enter a version string (for example, v1). This becomes part of the endpoint URL.

  4. Click Next.

Step 3: Configure settings

On the Settings step, configure runtime behavior:

  1. SSL only: Leave enabled. This requires HTTPS and is recommended for all production endpoints.

  2. Timeout: Set the maximum time API Manager waits for the operation to complete before returning a timeout error. The default is 30 seconds; the maximum is 180 seconds.

  3. Verbose logging: Enable during development to include request and response data in API logs. Disable in production to avoid large log files.

  4. Click Next.

Step 4: Configure the service endpoint

On the Services step, define how callers reach the operation:

  1. Method: Select the HTTP method callers will use. For read operations, select GET. For operations that accept a request body (data submission, record creation), select POST.

  2. Path: Enter the sub-path appended to the base URL (for example, /records or /submit).

  3. Response Type: Select how the operation returns its response to the caller:

    • Variable: The response body is the value assigned to $jitterbit.api.response in the operation. Use this for most cases, as it gives full control over the response content and status code. See Part 2 for details.
    • Final Target: The response is the output of a API Response activity at the end of the operation chain. Use this when the operation already terminates with an API Response activity.
    • No Response: API Manager returns an empty 202 Accepted immediately without waiting for the operation to complete. Use this for long-running fire-and-forget operations where the caller does not need a result.

  4. Click Next.

Step 5: Add a security profile

On the Security profiles step, assign at least one security profile to restrict access to the endpoint.

  1. To use an existing profile, enable the Assign toggle next to it.

  2. To create a new profile, click New security profile and follow the prompts. API key and Basic authentication are the most common choices for machine-to-machine integrations. For user-facing APIs that require identity, use OAuth 2.0.

    Tip

    Leaving the endpoint with no security profile assigned makes it publicly accessible to anyone with the URL. Always assign a security profile before publishing to production.

  3. Click Next.

Step 6: Publish

  1. On the User roles step, optionally restrict access by organization role. Click Next if no role restriction is needed.

  2. Click Publish.

    The API is live within five minutes. API Manager displays the full endpoint URL in the format https://<host>/<service-root>/<version>/<path>. Copy this URL to share with the API caller.

    Note

    A published API counts as one API URL against your Harmony subscription allowance. Save as Draft instead if you want to complete configuration before making the endpoint live.

Part 2: Return a response from the operation

When the Response Type is set to Variable, the operation must assign the response body to $jitterbit.api.response before it completes. Add a script step at the end of the operation (or at the end of the operation chain) to set this value.

  • Return a JSON response:

    <trans>
$jitterbit.api.response = JSONStringify($result_dict);
$jitterbit.api.response.status_code = 200;
</trans>

  • Return a plain string response:

    <trans>
$jitterbit.api.response = "Processing complete";
$jitterbit.api.response.status_code = 200;
</trans>

  • Return an error response:

    <trans>
$err_response = Dict();
$err_response["error"] = "Record not found";
$jitterbit.api.response = JSONStringify($err_response);
$jitterbit.api.response.status_code = 404;
</trans>

If $jitterbit.api.response is not set before the operation completes, API Manager returns an empty 200 OK response.

For a full list of API Jitterbit variables, see API Jitterbit variables.

Verify the integration

  1. Deploy the project if you have made any changes since publishing.

  2. In API Manager, copy the published endpoint URL from the APIs page.

  3. Send a test request to the endpoint using a tool such as curl or Postman, including the appropriate authorization header for the security profile you assigned.

  4. Confirm that the HTTP response body and status code match the values set in the operation.

  5. Open the API logs in API Manager and the operation logs in Studio to confirm the request was received and the operation completed successfully.

To add authentication to the operation itself (for example, to validate a JWT in a script step before processing the request), see Authenticate API endpoints using JWT.