Custom API Configuration¶

Introduction¶

This page describes how to create and configure a Custom API from the My APIs page of 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.

Alternatively, Custom APIs can be created in Cloud Studio using the Publish as an API option accessed from an operation's action menu.

Prerequisites¶

As a Custom API exposes a Harmony operation for consumption, such an operation must first be created and deployed in 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:

• Cloud Studio
  • Operation Creation and Configuration
  • Operation Deployment and Execution
• Design Studio
  • Creating an Operation

Create 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 Configure a Custom API below.

Configure a Custom API¶

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

• Step 1: Settings
• Step 2: Select Service Type and Assign Operations
• Step 3: Assign User Roles and Security Profiles
• Step 4: Summary and Confirmation

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 Get Started in API Service URL.

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

Step 1: Settings¶

• API Name: Enter a name for the API to use for internal identification purposes. These special characters are allowed:

  ( ) - _

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

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

• 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.1, v1.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.

• Add API Service: Click to add an API service to expose a Harmony operation for consumption. Once clicked, the individual API service configuration is opened (described below). Multiple API services can be added to a Custom API.

After clicking Add API Service, the configuration for an API service is opened:

• Request Method: Use the menu to select the request method for the API service, one of GET, POST, PUT, DELETE, ALL, or CUSTOM. Selecting ALL will create separate GET, PUT, POST, and DELETE methods for the selected Operation (the CUSTOM method is not included). By default, the request method is set to GET.

  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.

• Service Name: Enter a name for the API service.

• Path: Optionally, enter a path for the request. The path must begin with a forward slash / and must have all request parameters enclosed in curly brackets { }. Any other special characters are not allowed.

  Note

  The combination of request method and Path must be unique for each API service in the Custom API.

• Custom Method Name: Visible when CUSTOM is selected as the Request Method. Enter the name of the method to be used, for example, PATCH. (Alpha characters, hyphens -, and underscores _ only.)

• Operation: Within the Operation tab, you select a project and operation to assign to the API service (required to enable the Save button):

  • Assign Project: Use the menu to select a deployed project from the environment where the API is being configured (specified in Step 1: Settings).

  • Edit Project: When a Cloud Studio project is selected, this button is enabled. Clicking Edit Project opens the project in Cloud Studio in a new tab.

    Note

    You must deploy any changes made to the project for them to take effect.

  • Assign Operation(s): Use the menus to select an Operation and Response Type for the API service:

    • Operation: Select from the deployed operations in the selected project.

      Important

      By default, successful operations configured for a Custom 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.

    • 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, a Cloud Studio API Response activity or Variable Write activity, or a Design Studio API Response target or Global Variable 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.

• Path params: When request parameters are included in the Path, this tab is populated with these fields:

  

  • Parameter: Displays the request parameters defined in the Path.

  • Description: Optionally, enter a description for the request parameters.

• Query params: This tab allows you to add any query parameters to the API service:

  

  • Add Parameter: Click to add a query parameter to the API service. Once clicked, these fields become available:

    • Parameter: Enter the name of the query parameter.

    • Description: Optionally, enter the description of the query parameter.

    • Delete: Click the delete icon next to a query parameter to delete that parameter.

• Headers: This tab allows you to add any request headers to the API service:

  

  • Add Parameter: Click to add a request header to the API service. Once clicked, these fields become available:

    • Parameter: Enter the name of the request header.

    • Description: Optionally, enter the description of the request header.

    • Required: Select if the request header should be required for each API service request.

    • Delete: Click the delete icon next to a request header to delete that header.

• Duplicate: Click the duplicate icon to create a duplicate of the API service.

  Note

  Once the API service is duplicated, you must change either the request method or the Path as each API service must have a unique combination of those fields.

• Delete: Click the delete icon next to an API service to delete it from the Custom API.

• Save: Click to save the API service. When the configuration for all API services is complete, the Next and Save Changes buttons are enabled. An incomplete API service configuration is indicated with an error icon next to the name of the API service:

  

  To resolve and enable the Next and Save Changes buttons, complete the configuration or delete the API service.

• Cancel: Click to cancel the API service configuration.

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

  • 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.)

  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 Profiles. To 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.