This guide is intended for new users of API Manager, the only end-to-end real-time API solution that provides connectivity, service creation, and API management all on a single cloud platform. You will be guided through easy steps of connect, publish, and manage to provide real-time APIs for any cloud, on-premises, or mobile app.
NOTE: Users that are new to Jitterbit Harmony will need to complete the Jitterbit Admin Quick Start Tutorial prior to continuing through the API Manager Quick Start Guide. The Jitterbit Quick Start Tutorial directs you from the first steps of registering your Harmony account all the way through the completion of your first integration project and provides you with the basic foundation to move forward with API Manager.
Prerequisites to Working with API Manager
- Access to API Manager is determined by your Harmony subscription. If the API Manager application is not visible to you in the Harmony Portal, contact your CSM for additional information.
- A minimum of one environment and one agent group is required to create an API, OData Service, or a proxy API. An existing environment may be used for one or more APIs, or a new environment may be created for a specific API or a specific new group of APIs.
- A minimum of one user, role and member must be set up in the Harmony organization in order to access API Manager and create a Custom API, OData Service, or API Proxy.
- A minimum of one project that contains at least one functioning workflow or operation is required to create an API.
- Custom API: At least one API endpoint created either in Design Studio or in Cloud Studio is required. This guide includes an example operation with an API endpoint to create a custom API.
- Detailed instructions for setting up environments, agents and agent groups are available within the Management Console documentation.
- For best practices on working with environments in Jitterbit, watch the Environments Tech Talk.
- Complete instructions for setting up your organization, roles and members can be found under Organizations within the Management Console documentation.
- The initial steps to create a Cloud Studio project are detailed in the Cloud Studio Quick Start Guide. Information on using an API endpoint in conjunction with a Jitterbit Custom API is provided in the API section of the Cloud Studio documentation.
- The initial steps to create a Design Studio project, transformation and operation are detailed in Design Studio Quick Start Guide , Creating a New Project, and in the Operations and Transformations sections of the Design Studio documentation.
- For detailed instructions on setting up a Jitterbit Entity, see Creating a Jitterbit Entity and Creating an API Entity Operation.
Getting Started with API Manager
View the overview video and preview the steps to create a custom API.
Custom API Operation
- Assume that we want an external system to call our integration operation.
- This operation reads a database table.
- The API Response is chosen as the target or output, meaning that the output of the transformation will be returned to the calling system. The output must be a in a JSON or XML format. In this case, the API Response is in a JSON format.
- Within the transformation the data is mapped from the database Contacts table into a JSON output file.
Next, go to API Manager to build the API.
Create a New API
API Manager is accessed from the Harmony Portal. The credentials you use depend on if your organization and account is configured to use Single Sign-On (SSO). Once you are logged in to the Harmony Portal, you can access the My APIs landing page as follows:
- From the Harmony Portal landing page, select the API Manager card.
- From any page within the Harmony Portal, use the Harmony Portal menu in the top left corner to select API Manager
- From any page within API Manager, click the logo or words API Manager in the top left next to the menu.
The My APIs landing page displays the existing APIs for the selected organization. Statistics display the number of URLs that are currently published and in use against the total number of APIs provided under the organization's subscription.
Select New API in the upper right side of the page.
Step 1: Settings
The process of creating and publishing a new API consists of 4 steps, each step is a separate page, and the step number is highlighted at the top of the page. You can navigate back to a previous step by selecting the step numbers on top of the page, or you can select Cancel at the bottom of each page to stop the process at any time.
- Enter a name for the API in the API Name field. The name should be short and describe the functionality of the API, such as SAP Invoices or NetSuite Accounts.
- Select the Environment your API project resides in from the dropdown list.
- The Service Root is automatically populated with the API Name entered above, translated into camel case. If a different service root is preferred, enter the name in the Service Root field.
- Jitterbit uses camel case in the service root. The API Name entered as "Contact List" automatically populates the Service Root field as "contactList" using camel case. Additional information regarding camel case is available Lodash.com.
- The space between words and any underscore "_" entered between words in the API Name are ignored in the Service Root.
- The underscore "_" character may be entered manually within the Service Root field and is included in the final API URL.
- A manually entered space is not allowed in the Service Root or the final API URL.
All special characters, other than the underscore, are not allowed in the Service Root or the final API URL.
- Enter a version in the Version field.
Enter a short description of the API in the Description field.
- Enter the number of seconds in the TIMEOUT field. The default is 30 seconds. The maximum is 180 seconds.
- SSL Only is enabled by default and is recommended. To disable SSL only, click the checkbox to clear it.
Click the checkbox to enable CORS. A warning note displays. Review the warning and go to https://www.w3.org/TR/cors/ for additional information. Select Continue to enable CORS or Cancel to disable.
- Enable Verbose Logging: Click the checkbox to enable verbose logging. Verbose logging for APIs allows the user to decide whether each API log should contain request and response data. This functionality helps monitor incoming and outgoing data as well as facilitate debugging API issues.
- This option can be enabled or disabled at any time by hovering over the API card in the My APIs Index page and selecting View/Edit on the back side of the card.
- When this option is selected, a popup window displays. Select Continue to enable verbose logging, select Cancel to disable verbose logging and close the window.
- Select the checkbox to Enable Debug Mode Until. The default date is the date debug is enabled and the default time is exactly one hour from the time debug is enabled. A popup message describes the debug mode processing and the consequences of running in debug mode for a longer period of time. Debug logging can be turned on at any time by opening the API in View/Edit mode.
- Select Continue to enable debug mode or Cancel to disable.
- Once enabled, debug logging is set to run until exactly one hour from the date and time it is enabled. These are the steps to change the default date and time:
Click within the date field to display a calendar to set a longer period to run in debug mode. Two weeks is the maximum time allowed to enable running in debug mode.
Select the day in the calendar.
Click in the time field. Click the up and down arrows to set the hour and minutes.
- Click Set to accept the time. Click Cancel to close the popup without making changes.
- Debug logging can be turned on at any time by hovering over the API card in the My APIs Index page and selecting View/Edit on the back side of the card.
- Selecting Cancel will close the window without saving the information already completed.
- Select Next to continue to Step 2.
Step 2: Select Service Type and Assign Operation
To help determine the correct service type, hover over each information iconto view a description of Custom API and OData Service.
Select the radio button for the appropriate Service Type for your API. The project and operation used in this example are designed for a Custom API.
NOTE: The Service URL (shown here as
https://JitterbitTrial#####.jitterbit.org/Prod/v1.0/contactList) in the upper right side of the page is created as the fields are populated within the settings in Step 1:
https://JitterbitTrial#####.jitterbit.org: Composed from the organization's org number assigned at the time the subscription license is purchased.
/Prod: This is determined by the selection in the Environment field in Step 1 and is the value in the URL Prefix field of the environment. The URL Prefix field is populated at the time the environment is created. The URL Prefix is limited to a maximum of 48 characters. Detailed instructions for setting up environments are available within our existing Management Console documentation.
/v1.0: The value entered in the Version# field in Step 1.
/contactList: This is the value in the Service Root field in Step 1. In the example, we allowed the value entered in the API Name field to autofill the Service Root field using camel case.
Select your API Project from the dropdown list. The list displays the projects available in the environment selected in Step 1.
- Select the API Operation to call from the dropdown list. The list displays the operations available in the project you selected.
- Select the Method type (Get, Post, Put, Delete, All unassigned types, Custom Type) from the dropdown list.
- For additional information on Get, Post, Put and Delete methods, see https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods.
- Selecting All unassigned types will create a separate Get, Post, Put and Delete method for the selected operation.
- Select the Response Type (Final Target, System Variable, No Response) from the dropdown list. To help determine the correct response type, select each of the three types individually and hover over the information icon to display a description, requirements, and consequences of selecting each type. Select the appropriate response type from the dropdown. Final Target is selected for this example.
Select Assign Operation. At least one operation must be assigned in order to continue through the remaining steps to create the API.
- The assigned selections display in the grid at the bottom of the page.
- Repeat Step 2 to assign additional methods to the same operation, or to assign multiple operations and methods to the API. Once completed, all assigned operations and associated methods display in the grid.
- Select the delete icon to the right if any of the settings are incorrect and repeat Step 1 and Step 2 with the correct information.
- Selecting Cancel saves the API as a draft. The information entered to this point is saved and may be updated and published later. As a draft, the API is not accessible and does not increase the number of APIs used against your subscription limit.
- Select Next to continue to Step 3.
Step 3: Assign Security Profiles
Select Skip this Step at the bottom of the page to continue to Step 4 without assigning any security profile to the API. If the API is published prior to assigning a security profile, it is anonymous and publicly accessible by default at the time it is published. Currently there are 3 types of authentication available in API Manager: Anonymous, Basic and OAuth 2.0. OAuth 2.0 is currently limited to Google, Salesforce, or Okta as the identity provider (IdP). See Harmony API Security and Security Profiles for more information.
Select the appropriate Profile from the dropdown list or select the Create New Profile link to open the Security Profiles page and create a new profile. When you save the new profile, you are returned to Step 3 to assign the new profile to the new API you are creating.
The existing Accounting profile is selected for this example.
Select Assign Profile.
The profile assignment displays in the grid at the bottom of the page.
- Repeat this step to assign multiple security profiles to the API.
- Select the delete icon to delete a profile.
- Selecting Cancel saves the API as a draft. The information entered to this point is saved and may be updated later. As a draft, the API is not accessible and does not increase the number of APIs used against your subscription limit.
- Select Next to continue to Step 4.
Step 4: Publish New API
The Summary & Confirmation page presents all the settings and selections made within Steps 1 through 3, allowing the user to review, confirm, and edit the information prior to publishing the API.
- To edit information or settings in Step 1, Step 2 or Step 3, select the edit icon to the right of the section.
- You will be returned to the Step 1, Step 2 or Step 3 page.
- Follow the instructions above to change settings or selections in Step 1, Step 2 or Step 3 and save each step to return to the Summary & Confirmation page.
- When all the settings on the Summary & Confirmation page have been corrected and/or verified, select Save & Publish at the bottom of the page.
- Each section of the page corresponds to a previous step, beginning with the Settings from Step 1 that include the API name, environment, and description.
- The Time Out, SSL, CORS and Debug settings are enabled if they have a check mark to the left. Each setting that has an to the left is disabled.
- Selecting the edit icon to the right of the section returns the user to the Step 1 page for editing.
- When changes and additions are complete, select Continue on Steps 1 through 3 to return to the Summary & Confirmation page.
- The Operations section displays the project, operations and methods assigned to the API in a grid.
- Selecting the edit icon to the right returns the user to the Step 2 page for editing.
- When changes and additions are complete, select Continue on Steps 2 and 3 to return to the Summary & Confirmation page.
- The Security Profiles section displays every profile assigned to the API in the grid.
- Selecting the edit icon to the right returns the user to the Step 3 page for editing.
- When changes and additions are complete, select Continue to return to the summary and confirmation page.
Your API is Live!
After selecting Save & Publish, the API is live and accessible based on the assigned security profiles. The API increases the number of APIs used against your subscription
Click on Copy URL and paste the URL into your browser for a quick test. For this example, the operation responds with JSON output:
Select Generate OpenAPI document to open the Portal Manager. You can generate the OpenAPI document and test the API in the Portal Manager.
- Select Dismiss to close the popup window.
The Portal Manager allows you to activate, customize, invite consumers, and control which APIs are exposed to consumers. OpenAPI 2.0 (formerly known as Swagger 2.0) documentation is automatically generated for your published APIs.
The portal is accessible by selecting View/Edit Documentation immediately after publishing a new API. The portal is also accessible from any page within API Manager by selecting My APIs in the upper left corner and Portal Manager in the dropdown.
NOTE: If this is the first time you have accessed the Portal Manager, this message displays: "No active developer portal was found for your organization. Would you like to create one now?"
Follow these steps to initialize the portal:
OpenAPI 2.0 documentation for each API displays on the left side of the portal. Each API is listed by URL and by method on the right side of the portal.
For additional information about using OpenAPI 2.0 to document your APIs, please see OpenAPI Specification.
- Test the API within the portal as follows:
- Select Authorize to enter the required credentials. (Credentials are required if the Lock icon is located to the right of the API URL.)
- Select Get.
- Select Try It Out.
- Select Execute.
The API executes within the Portal Manager and the operation responds with the JSON output.
Select My APIs in the upper left corner and API Logs in the dropdown. API Logs include API operation logs as well as debug logs (if debug logging is enabled). API Logs
- Determine the range of logs to display by selecting View Data in the upper right corner and selecting the timeframe in the dropdown.
The first two entries listed on this page are the two test runs performed on the example API; the first run was at the time the API was created and the second run was from within the Portal Manager.
- Select the orange Plus sign at the end of the row and view more details for a specific log entry.
Debug logs contain a great deal of searchable information about the inbound or outbound call. The debug logs can also be downloaded by selecting Download to CSV at the top of the grid.