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:
-
The organization being accessed must have a subscription to API Manager and have the appropriate role 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:
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 asv1.0
,v1.1
,v1.2
, or using a date that the API was published, such as2023-09-21
. -
Timeout: Enter the number of seconds before the API will time out. The default is
30
seconds. The maximum is180
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
, andPUT
request methods for the operation (theCUSTOM
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:
- 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: 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:
- 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.