OData API configuration in Jitterbit API Manager

Introduction

This page describes how to create and configure an OData API from the APIs page of Jitterbit API Manager. An OData API is one of the three types of APIs configured through API Manager. For the two other types, custom API and proxy API, see Custom API configuration and Proxy API configuration.

OData APIs (published and draft) are displayed in these locations:

• The APIs page of API Manager.
• The project pane's Resources tab for the Design Studio project associated with the OData API.

Prerequisites

An OData API exposes a Jitterbit iPaaS API entity operation for consumption. You must first create and deploy this operation before you can configure the OData API. The operation that an OData API triggers must be a Design Studio API entity operation.

For information on creating and deploying an API entity operation in Design Studio, see these resources:

• Design Studio quick start guide
• Create a Jitterbit entity
• Create an API entity operation

Create a new OData API

When you access the API Manager APIs page, if no custom APIs, OData APIs, or proxy APIs exist in the selected organization, this screen is blank.

To create a new OData API, click New > OData API.

Configure an OData API

The configuration screen includes multiple tabs, with two required tabs and three optional tabs. Each tab is covered in the following sections:

• Profile tab (required)
• Settings tab (optional)
• Services tab (required)
• Security profiles tab (optional)
• User roles tab (optional)

Profile tab

Use the Profile tab to enter basic information that identifies the API.

Configure the following settings:

• API Name: Enter a name for the API to use for internal identification purposes. The following special characters are allowed: ( ) - _.

• Service Root: The public name of the API to use as part of the API's service URL. By default, this field is populated with the API Name converted to camel case. This field does not allow spaces or certain special characters. Using special characters other than an underscore (_) is not recommended. The following special characters are allowed: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

• Description: Enter an optional description for the API.

• Environment: Use the menu to select the environment where the API will reside. You can type any part of the environment name into the menu to filter the list of environments. The menu results are filtered in real time with each keystroke.

  Note

  After API creation, you cannot change the environment. To move an API between environments, you can clone the API or export and import the API in another environment.

• Version number: Enter an optional version to use as part of the API's service URL. This field allows a maximum of 48 characters and does not allow spaces or certain special characters. Using special characters other than a period (.) or a hyphen (-) is not recommended. Common naming conventions include incrementing versions such as v1.0, v1.1, v1.2, or using a date that the API was published such as 2025-08-28.

After you complete the Profile tab, click Next to proceed to the Settings tab, or click Save as draft to save your progress.

Settings tab

The Settings tab is optional and contains advanced configuration options for the API.

Configure the following settings as needed:

• Timeout: Enter the number of seconds before the API will time out. The default is 30 seconds. The maximum value allowed is 180 seconds.

  Note

  This setting is independent of the operation timeout setting in Studio or Design Studio. Operation timeout settings are not used unless a private agent is used and the EnableAPITimeout setting in the private agent configuration file is enabled.

• SSL only: This toggle is enabled by default and requires HTTPS for the API. When enabled, data is encrypted through SSL, and an HTTP request returns an error. When disabled, both HTTP and HTTPS requests are supported.

  Warning

  When disabled, data passed through API requests and responses is not encrypted and can be intercepted and viewed by others. This could potentially expose sensitive information.

• CORS: Enable this toggle to support CORS (Cross-Origin Resource Sharing). CORS is a mechanism that allows web applications running in a web browser on one domain to access resources from a server on a different domain.

  Warning

  Enabling CORS causes operations using the OPTIONS method to run without authentication.

• Verbose logging: Enable this toggle to log request headers and payloads when an API request is made.

  Warning

  Verbose logging may include sensitive data such as authentication credentials or personally identifiable information. Use this setting carefully.

• Enable debug mode until: Enable this toggle to turn on detailed logging for troubleshooting, then click the calendar icon to select a date up to two weeks from today when debug mode automatically turns off. When you enable debug mode for operations triggered by this API, the API logs include request and response data (kept for 30 days) that you can access through the Management Console Runtime page. By default, API Manager logs only API operations with errors.

  Warning

  Debug logs contain all request and response data, including sensitive information such as passwords and personally identifiable information (PII). This data appears in clear text in Harmony cloud logs for 30 days.

After you configure the Settings tab, click Next to proceed to the Services tab, or click Prev to return to the Profile tab.

Services tab

The Services tab is where you configure the API services that define how the API responds to requests. For OData APIs, you assign Jitterbit entity operations that expose data through the OData protocol.

Click New Service to add a new API service. Configure the following settings for each service:

• Entity: Select from the deployed projects that contain a Design Studio API entity operation in the environment where you are configuring the API. The entity name corresponds to the project name in Design Studio.

• Project: Displays the Design Studio project name that contains the selected entity.

• Operation: Select from the deployed Design Studio API entity operations in the selected entity. Only one operation using each method can be assigned.

  Important

  By default, successful operations configured for an OData API are not included in the operation logs unless one of these settings is enabled:

  • Cloud agents: For API operations on a cloud agent, operation debug logging must be enabled on the operation.
  • Private agents: For API operations on a private agent, either operation debug logging must be enabled on the operation or you must set EnableLogging=true in the [APIOperation] section of the private agent configuration file.

  Unsuccessful operations are included in the operation logs whether the above settings are enabled or not.

• Method: Select the HTTP method to be created for the selected operation. Available methods include GET, PUT, POST, DELETE, PATCH, MERGE, or ALL. Selecting ALL creates separate GET, PUT, POST, DELETE, PATCH, and MERGE methods for the selected operation. To use a method not listed, enter the method name in the Type a new method text box and press Enter.

• Actions: Hover over a service row to reveal additional actions.

  • Copy API service URL: Click to copy the API's service URL.
  • Go to API Service: Click to see a single page overview of the OData API's configuration.
  • Duplicate: Click to duplicate the API service.
  • Delete: Click to delete the API service.

You can configure multiple services for a single OData API. You must add at least one entity to proceed to the next tab.

After you configure the Services tab, click Next to proceed to the Security profiles tab, or click Prev to return to the Settings tab.

Security profiles tab

The Security profiles tab is optional and allows you to restrict access for consumption of the API.

Configure the following settings:

• Assign: Use the toggle to assign or unassign security profiles for the API.

• Profile Name: The name of the security profile as configured in Security Profiles.

• Type: The authentication type for the security profile, such as Basic, OAuth 2.0, or API Key.

• User Name: For basic authentication, this displays the username. For other authentication types, this displays the same value as the Type column.

• Actions: Hover over a security profile row to reveal additional actions.

  • Go to security profile: Click to open the security profile's configuration.

Depending on the Harmony organization's policies, you may be required to assign a security profile in order to save the API.

Click New security profile to create a new security profile. For instructions, see Configure security profiles.

After you configure the Security profiles tab, click Next to proceed to the User roles tab, or click Prev to return to the Services tab.

User roles tab

The User roles tab is optional and determines which organization roles have access to the API within API Manager.

Configure the following settings:

• User Role: The name of the organization role as defined on the Roles tab of the User Management page.

• Permissions: The permissions assigned to this role, such as Read or Admin.

• Status: Indicates whether the role is assigned to this API. Toggle the status to assign or unassign roles.

• Actions: Hover over a user role row to reveal additional actions.

  • Go to user role: Click to open the user role's configuration.

The roles you select here determine access to this specific API from these pages:

• APIs
• Portal Manager, including generation of API documentation
• API Portal
• API Logs
• Analytics

Access to the Security Profiles page and access to consume the API are unaffected by this selection. Access to consume an API is controlled by security profiles.

Any defined user roles with the Admin permission always have full access to all APIs and therefore cannot be cleared from selection.

Click New user role to create a new user role. For instructions, see Roles in User Management.

After you configure the User roles tab, click Publish to publish the API, or click Save as draft to save your progress.

Save and publish options

After you configure all required tabs, you can save or publish the API:

• Save as draft: Saves the API in Draft status or Published with Draft status. Draft APIs do not count against your API URL subscription limit. An API whose status was Published at the time you use Save as draft is saved as Published with Draft. A published API counts against your API URL subscription limit, even though its draft is not accessible.

• Publish: Saves the API in Published status. The API is live and accessible within five minutes. A published API counts against your API URL subscription limit. A dialog indicates the API is live:

  

  The dialog provides these options:

  • Copy URL: Copies the API's service URL to your clipboard.
  • Generate OpenAPI Document: Opens the Portal Manager page. Note that you can generate OpenAPI documentation for custom APIs only, not for OData APIs.
  • Close: Closes the dialog.

OData query parameters

You can filter the data being returned by appending OData query parameters to an OData API service URL. The specific query parameters supported depend on the underlying database.

Common OData query parameters include:

https://jbexample.jitterbit.net/Sandbox/customers?$top=10&$orderby=name

Edit the API

After you save the API, you can edit it from these locations:

• Using tile view in the APIs page, click View/Edit.
• Using list view in the APIs page, click Edit in the Actions column.