Skip to Content

Publish an operation as an API

Introduction

This page describes how to configure and publish a custom API (to expose an operation for consumption) from within Integration Studio. The Publish as an API option is accessible from an operation's action menu.

Alternatively, custom APIs can be created from the API Manager My APIs page.

Note

Once published, a custom API counts as an API URL against your Harmony subscription allowance.

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

  • The My APIs page of API Manager.
  • The project pane's Resources tab for the Integration Studio project associated with the custom API.

Prerequisites

To use the Publish as an API option in the operation's action menu, these prerequisites must be met:

Configure the API

After clicking the Publish as an API option on the operation's action menu, a custom API configuration dialog opens with these settings:

cs custom API configuration

Note

Optional settings such as path parameters, query parameters, and request headers can be set in API Manager (see Step 2: Select service type and assign operations in Custom API).

  • API name: Enter a name for the API to use for internal identification purposes. By default, this field is populated with the name of the operation.

  • 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 operation 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. These special characters are allowed:

    _ ~ ( ) $ ; / \ ? : @ = & ' ! * @ , + -

  • Description: Enter an optional description for the API.

  • Additional settings: Click to expand additional settings:

    • Environment: This field is set to the environment of the project currently being accessed and cannot be changed.

    • Version number: Enter an optional version to use as part of the API's service URL. This field allows a maximum of 50 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 2023-09-21.

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

      Note

      This setting is independent of the Operation time out setting available within the operation's Options tab. Operation timeout settings are not used for API Manager APIs unless a private agent is used and the EnableAPITimeout setting in the private agent configuration file is enabled.

    • Enable debug mode until: Select to enable debug mode and enable entering a corresponding date and time on which debug mode will be disabled. The maximum length of enablement is two weeks. Debug mode enables full tracing for every request received through the API's service URL. When enabled, the system retains complete content of each API request and response for up to 24 hours from the time the API call was received and applies to all operations triggered by the API.

    • SSL only: This option is selected by default and requires the use of SSL encryption (recommended).

    • Enable CORS: Select to enable Cross-Origin Resource Sharing (CORS) (not recommended).

    • Enable verbose logging: Select to enable verbose logging. Verbose logs for APIs include request and response data in each API log to help monitor incoming and outgoing data and facilitate debugging. As this can create large log files, verbose logging is disabled by default.

  • Service name: Enter a name for the API service. By default, this field is set to the operation's name.

  • Project: The name of the project currently being accessed.

  • Operation: The name of the operation being exposed for consumption.

  • Method: Select from one of ALL, CUSTOM, DELETE, GET, POST, or PUT as the request method to be used for the selected operation. Selecting ALL will create separate DELETE, GET, POST, and PUT request methods for the operation (the CUSTOM method is not included).

    Note

    API services using a CUSTOM method will not have OpenAPI documentation generated through the Portal Manager page due to a limitation of the OpenAPI specification.

  • Response type: Select from one of Final Target, System Variable, or No Response:

    • Final Target: The API response is the final target of the operation. When this response type is selected, the operation must have (as the final target of the operation chain) an Integration Studio API Response activity. If any other final target is used, the API response will be empty.

    • System Variable: The API response is set in a Jitterbit variable in the operation. When this response type is selected, the operation must have (as part of an operation chain) a script that sets the Jitterbit variable jitterbit.api.response equal to the response that you want the API to return. If this variable is not set, the API response will be empty.

    • No Response: The API response is blank. If the request to run the selected operation is accepted, the API will return an immediate empty response with HTTP code 202.

  • User roles: Select the organization roles whose members will have access to the API from within the API Manager pages listed below. The roles to choose from are those defined within the Management Console User Management page.

    This determines access to this specific API from these pages:

    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. (In the example screenshot shown above, the Administrator role cannot be cleared for that reason.)

  • Profile: Optionally, use the menu to select an existing security profile to restrict access for consumption of the API.

    Note

    If there are no existing security profiles configured for the currently accessed environment, you can configure one in API Manager. For instructions, see Security profile configuration.

  • Publish: Saves the API in Published status. The API is live and accessible within five minutes. A published API counts as an API URL against your Harmony subscription allowance. You can access the published API from the API Manager My APIs page.

  • Save Draft: Saves the API in Draft status and is accessible from the API Manager My APIs page. A draft API does not count as an API URL against your Harmony subscription allowance. You can access and complete the configuration of the draft API from the API Manager My APIs page.

  • Cancel: Closes the dialog without saving.

Important

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

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