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 Cloud 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.

Prerequisites¶

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

• The organization being accessed must have a subscription to API Manager and have the appropriate organization permissions and environment access levels. For information about adding API Manager to your license, contact your Customer Success Manager (CSM).

• The operation must not have any undeployed changes.

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:

• 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 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) a Cloud 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 Organizations page (see Managing Roles and Permissions under Organizations).

  This determines access to this specific API from these pages:

  • My APIs
  • Portal Manager, including generation of API documentation
  • 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. (In the example screenshot shown above, the Administrator role cannot be cleared for that reason.)

• Profile: Use the menu to select an existing security profile that will be used to restrict access for consumption of the API. A security profile must be assigned in order to save the API.

  Note

  If there are no existing security profiles configured for the currently accessed environment, you must 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.