Skip to end of metadata
Go to start of metadata

Introduction

This page describes how to create and configure a Custom API or OData Service from the My APIs page of Jitterbit Harmony API Manager. Custom APIs and OData Services are two of the three types of APIs configured through API Manager. For the third type — Proxy API — see Proxy API Configuration. On this page, the word API is used both to refer to a Custom API and to an OData Service.

As a Custom API or OData Service exposes a Jitterbit Harmony operation for consumption, such an operation must first be created and deployed in the Jitterbit Harmony cloud. The existing operation is then referenced during the configuration of the Custom API or OData Service:

To create and deploy an operation, see these resources:

When published, each Custom API and each OData Service count as an API URL in your Jitterbit Harmony subscription.

Creating a New Custom API or OData Service

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 or OData Service, click New API:

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

Configuring a Custom API or OData Service

The Custom API and OData Service configuration screen includes four configuration steps, each covered below:

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

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

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 hyphen (-) is not recommended. Example naming conventions include incrementing versions, such as v1.0, v1.1v1.2, etc., 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.
  • SSL Only: Select to use SSL encryption (recommended). The default is selected.
  • Enable CORS: Select to enable Cross-Origin Resource Sharing (CORS) (not recommended). The default is unselected.

    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. The default is unselected.
  • Enable Debug Mode Until: Select to enable debug mode and enter 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 continue to the next step.
  • Save Changes: Click to save the configuration for this step and navigate to Step 4: Summary and Confirmation.

Step 2: Select Service Type and Assign Operations

  • Service Type: Select the type of API, one of Custom API or OData Service:
    • Custom API: Custom APIs allow you to trigger, consume, and expose any Jitterbit Harmony operation.
    • OData Service: OData services provide you with a uniform way of creating and consuming data APIs.
    NOTE: Once the button Assign Operation for a Custom API or Assign Entity for an OData Service is clicked (as described in the next sections), the Service Type cannot be changed.

Custom API

When the selected Service Type is Custom API, the Assign Operation(s) section is displayed:

  • 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. 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 continue to the next step.
  • Save Changes: Click to save the configuration for this step and navigate to Step 4: Summary and Confirmation.

OData Service

When the selected Service Type is OData Service, the Assign Jitterbit Entities section is displayed:

  • Assign Jitterbit Entities: Use the dropdowns to select an Entity (Project), Operation, and Method for the OData Service:
    • Entity (Project): Select from the deployed projects that contain a Design Studio API Entity Operation in the environment where the API is being configured.
    • Operation: Select from the deployed Design Studio API Entity Operations in the selected Entity (Project). Only one operation using each method can be assigned.
    • Method: Select from one of GET, PUT, POST, DELETE, PATCH, MERGE, or ALL the method to be created for the selected Operation. Selecting ALL will create separate GET, PUT, POST, DELETE, PATCH, and MERGE methods for the selected Operation.
  • Assign Entity: Once all dropdowns are completed, click Assign Entity to add the entity to the table below. At least one entity must be added to enable the Next button.

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

Step 3: Assign User Roles and Security Profiles

  • Assign User Roles: Select the roles whose members will have access to the Custom API or OData Service 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 affects access to this specific Custom API or OData Service from these pages:

    Access to the Security Profiles page and access to consume the API are unaffected by this selection. (Access to consume the 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 API Exports and Imports).
  • 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 that whose status was Draft at the time Save as Draft is 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. Though this link appears for both Custom APIs and OData Services, OpenAPI documentation can be generated for Custom APIs only.
    • Dismiss: Closes the dialog.

  • No labels