Skip to end of metadata
Go to start of metadata

Introduction

This page describes how to create and configure a Custom API from the My APIs page of Jitterbit Harmony API Manager. Custom APIs are one of the three types of APIs configured through API Manager. For the two other types — OData Service and Proxy API — see OData Service Configuration and Proxy API Configuration

NOTE: Once published, each Custom API counts as an API URL against your Jitterbit Harmony subscription allowance.

Prerequisites

As a Custom API exposes a Jitterbit Harmony operation for consumption, such an operation must first be created and deployed in Jitterbit Harmony. The existing operation is then referenced during the configuration of the Custom API. The operation that a Custom API triggers can be either a Cloud Studio or Design Studio operation.

For instructions on creating and deploying an operation, see these resources:

Creating a New Custom API

When you access the API Manager My APIs page, if no Custom APIs, OData Services, or Proxy APIs exist in the selected organization, this screen is blank.

To create a new Custom API, click New API:

On clicking New API, the Custom API configuration screen opens. Details on configuring a new Custom API are provided in Configuring a Custom API below.

Configuring a Custom API

The configuration screen includes four configuration steps, each covered below:

An API's service URL is the URL used to consume the API using a configured authentication method. The parts of an API's service URL are described under API Manager Getting Started in API Service URL.

The Service URL is displayed along the top of each step:

Step 1: Settings

  • API Name: Enter a name for the API to use for internal identification purposes.
  • Environment: The environment where the API resides.

    NOTE: After API creation, the environment cannot be changed. To move an API between environments, you can clone the API or export and import the API in another environment.
  • 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.
  • Version: 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.1v1.2, or using a date that the API was published, such as 2021-08-28.
  • Description: Enter an optional description for the API.
  • 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 timeout setting in Cloud 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: Select to require the use of SSL encryption (recommended). SSL Only is selected by default.
  • Enable CORS: Select to enable Cross-Origin Resource Sharing (CORS) (not recommended). Enable CORS is selected by default.

    WARNING: Enabling CORS causes operations using the OPTIONS method to run without authentication.
  • Enable Verbose Logging: Select to enable verbose logging. Verbose logging for APIs includes 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, the default is that verbose logging is disabled.
  • 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.

    NOTE: Traversing through the event data may become difficult with large volumes (load testing, pre-production testing, etc.). The increase in retained data may result in storage space and security concerns. We do not recommend using debug mode in a production environment.
  • Next: Click to temporarily store the configuration for this step and to continue to the next step.
  • Save Changes: Click to save the configuration for this step and to navigate to Step 4: Summary and Confirmation.

Step 2: Select Service Type and Assign Operations

  • Service Type: Select Custom API.
  • Assign Operation(s): Use the dropdowns to select a Project, Operation, Method, and Response Type for the Custom API:
    • Project: Select from the deployed projects in the environment where the API is being configured.
    • Operation: Select from the deployed operations in the selected project.
    • Method: Select from one of GET, PUT, POST, DELETE, ALL, or CUSTOM the method to be created for the selected operation. Selecting ALL will create separate GET, PUTPOST, and DELETE methods for the selected Operation. Only one operation using each method can be assigned.
    • 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 chain. When this response type is selected, the selected operation must have, as the final target of the operation chain, either a Cloud Studio API Response activity or a Design Studio API Response target. 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 chain. When this response type is selected, the selected operation must have, as part of the 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.
  • Assign Operation: Once all dropdowns are completed, click Assign Operation to add the operation to the table below the button. At least one operation must be added to enable the Next button.

    NOTE: After clicking Assign Operation, you will no longer be able to change the Service Type.
  • Assigned Operations: A table displays all operations that have been assigned. To remove an assigned operation, click the remove icon .
  • Next: Click to temporarily store the configuration for this step and to continue to the next step.
  • Save Changes: Click to save the configuration for this step and to navigate to Step 4: Summary and Confirmation.

Step 3: Assign User Roles and Security Profiles

  • Assign 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:

    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 and Operations roles cannot be cleared for that reason.)

    NOTE: APIs created prior to Harmony 10.22 have all user roles selected by default to ensure continued access for all users.
  • Assign Security Profile(s): Use the dropdown to select an existing security profile that will be used to restrict access for consumption of the API. A security profile may be required to be assigned in order to save the API, depending on the Harmony organization's policies.
    • Assign Profile: Click to assign a selected security profile to the API. Assigned security profiles are listed in the table with the Profile Name and Type as configured for the security profile in Security Profile Configuration. If the Type is Basic, the Username column displays the Username provided during configuration. If the Type is any other type, the Username column displays the same value as the Type. To remove an assigned profile, click the remove icon .
    • Create New Profile: Click to create a new security profile. For instructions, see Security Profile Configuration.
  • Next: Click to temporarily store the configuration for this step and continue to the next step. If the API is not assigned a required security profile, this option is disabled.
  • Save Changes: If enabled, click to save the configuration for this step. If the API is not assigned a required security profile, this option is disabled.
  • Skip This Step: If present, click to continue to the next step without storing the configuration for this step. If the API is not assigned a required security profile, this option is not present.

Step 4: Summary and Confirmation

  • API Name and Environment: The API name followed by the environment enclosed in parentheses, as configured in Step 1: Settings.
    • Description, Timeout, SSL Only, CORS Enabled, and Verbose Logging Enabled: The API description and other settings that are enabled () or disabled (). To make changes to those settings, click the edit icon  to return to Step 1: Settings.
    • Enable Debug Mode Until: This option is the same as that described in Step 1: Settings. You can change this setting directly from this step rather than be required to return to the first step.
  • Operations: The operations assigned in Step 2: Select Service Type and Assign Operations with the corresponding information for the selected service type. To make changes, click the edit icon  to return to Step 2: Select Service Type and Assign Operations.
  • User Roles and Security Profiles: The roles and security profiles assigned in Step 3: Assign User Roles and Security ProfilesTo make changes, click the edit icon  to return to Step 3: Assign User Roles and Security Profiles.
  • Export: Generates and initiates a download of an APK file (apis-export.apk) containing an export of the API (see Exporting and Importing APIs).
  • Clone: Creates a copy of an existing API. In the API copy, the API Name is prepended with Copy of, the Service Root is prepended with Copyof, and the Version is appended with -2. The API copy is immediately opened at its own Step 4: Summary and Confirmation.
  • Delete: Permanently deletes the API and closes the configuration. A dialog asks you to confirm you want to delete the API.

    NOTE: If the API's status was Published or Published with Draft at the time of deletion, it is also removed from the number of API URLs used against your subscription limit. If the API's status was Draft at the time of deletion, the number of API URLs used against your subscription limit does not change, as the API was not accessible while in Draft status.
  • Save as Draft: Saves the API in Draft status or Published with Draft status:
    • Draft: A new API or an API whose status was Draft at the time Save as Draft was used. Drafts do not count against your API URL subscription limit.
    • Published with Draft: An API whose status was Published at the time Save as Draft is used. An API that is published with a draft counts against your API URL subscription limit, as the API is accessible though its draft is not.
  • Save and 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, as the API is accessible. A dialog indicates the API is live:

  • Copy URL: Copies the API's service URL (see API Service URL).
  • Generate OpenAPI Document: Opens the Portal Manager page, where you can generate API documentation for the Portal page.
  • Dismiss: Closes the dialog.

  • No labels