Skip to end of metadata
Go to start of metadata

Introduction

This page describes how to create and configure a new API, access existing APIs, and edit the configuration settings of existing APIs. 

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 into 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 hamburger menu in the top left corner to select API Manager > My APIs
  • From any page within API Manager, click the logo or words API Manager in the top left next to the menu.

TIP: Before creating an API, you should have already registered for Jitterbit Harmony (through the Jitterbit Harmony website). You will also need to set up at least one environment , agent group, user, role, and member (as described in the Jitterbit Quick Start Tutorial), and created a project (as described in the Cloud Studio Quick Start Guide or the Design Studio Quick Start Guide). A quick review of the Prerequisites section in the API Manager Quick Start Guide is also recommended prior to creating your API.

Getting Started

View this video to preview the steps to create a custom API.

Create a New API

When you access API Manager, if no APIs exist in the selected organization, this page will be blank. Click New API in the upper right side of the page to get started:

Selecting New API opens the Publish New API page. The process of creating and publishing a new API consists of four 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.

Step 1: Settings

  • API Name: Enter a name for the API. The name should be short and describe the functionality of the API. The API name is important for internal identification and is also used in the service root (the public name) of the API. The name automatically becomes part of the API URL.
  • Environment: Click in the Environment field to display the dropdown list.  Select in the list the Environment your API project resides in.
  • Service Root: The Service Root field is automatically populated with the API Name entered above and is 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 on 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 then 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.

  • Version#: Define a version method for this API and enter the version in the Version# field. While this is not required, it is highly recommended. The V1, V2, etc. naming convention is often utilized. You can use any alphanumeric character for the version, including a date. Special characters are not allowed in the version, except the period and the dash. A maximum of 48 characters is allowed in the version field. The version will also become part of the URL to help you and your customers distinguish your various APIs in the future.
  • Description: Enter a short description of the API in the Description field. This description will appear in the My APIs index and may be useful to help project collaborators identify the API.
  • Scroll down to the TIMEOUT field.

  • TIMEOUT: Enter the number of seconds before the API will time out. The default is 30 seconds. The maximum is 180 seconds.
  • SSL Only: SSL communication security is enabled by default and is strongly recommended. To disable SSL only, click the checkbox to clear it. 
  • Enable CORS: 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 CORS and close the popup window.

  • 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.
  • Scroll down to Enable Debug Mode Until.

  • Enable Debug Mode Until: Debug logging is disabled by default. Click the checkbox to enable debug logging. 
    • A popup message describes debug mode processing and the consequences of running in debug mode for a longer period of time.
    • Select Continue to enable debug mode or Cancel to disable debug mode and close the popup window.
    • 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. 
  • Next: Select Next to save the information entered in step 1 and continue to step 2.
  • Cancel: Selecting Cancel at the bottom of the page or selecting the close icon  in the top right corner of the page, will close the page without saving the information already entered in step 1.
  • Save Changes: This option is available only after opening an existing API to edit, and it is activated only after changes are made to the page. Click Save Changes to save the changes you made in this page. A popup window displays a message giving you the option to Save Changes or Discard Changes. Click Save Changes to save the changes you made, close the popup, and return to the Summary & Confirmation page. Click the Discard Changes link to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page.
  • Discard Changes: This option is available only after opening an existing API and only after you have made changes to the page. Click the Discard Changes link if you do not want to save the changes you made to this page. A popup windows displays a message giving you the option to Save Changes or Discard Changes. Click Discard Changes to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page. Click the Save Changes link to save the changes you made, close the popup, and return to the Summary & Confirmation page. 

Step 2: Select Service Type and Assign Operations

  •  Service URL: The Service URL displays at the top of the page in Steps 2 through 4. As shown above, the service URL is https://JitterbitTRIAL######.jitterbit.org/ProdS/v1.0/contactList. The service URL is created as the fields are populated within the settings in step 1
    • https://JitterbitTrial######.jitterbit.orgThis is the base API URL for your org. The base URL is composed of your organization's org number, assigned at the time the subscription license is purchased (Format: JitterbitTrial#####), and your Harmony region (APAC, EMEA, NA).
      • APAC Region Base URL: JitterbitTrial#####.Jitterbit.cc
      • EMEA Region Base URL: JitterbitTrial#####.Jitterbit.eu
      • NA Region Base URL: JitterbitTrial#####.Jitterbit.net
    • /ProdS: 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 on the Environments page.
    • /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
  • Service Type: To help determine the correct service type, hover over each information icon  to 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. 
  • Scroll down to Assign Operations.

  • Projects: Click on Projects to display the list of the projects available in the environment selected in step 1. Select your API Project from the list. 

  • Operation: Click on Operation to display the list of the operations available in the project you selected. Select the API Operation from the list. 
  • Method: Click on Method to display the list of method types (Get, Post, Put, Delete, All unassigned types, Custom Type). Select the Method type from the list. 
  • Response Type: Click on Response Type to display the list of response types (Final Target, System Variable, No Response). Select the Response Type from the list.

    TIP: 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.

  • Assign Operation: This button is activated once the project, operation, method, and response type are selected. Click 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 table at the bottom of the page as shown in the image below.

  • 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 table.
  • To delete an operation, hover over the row and select the delete icon .
  • To make changes to an assigned operation, click on the row in the table.

    • The row is now highlighted, and the Projects, Operation, Method, and Response Type fields are now populated with the selected operation information.
    • Make the necessary changes in the Projects, Operation, Method, and Response Type fields.
    • Save Changes: Select Save Changes to save the changes to the selected operation and remain on the page.
    • Cancel: Select Cancel (above the table) to cancel the changes entered for the selected service and remain on the page.
  • Next: Select Next to save the information entered in step 2 and continue to step 3.
  • Cancel: Selecting Cancel at the bottom of the page or selecting the close icon  in the top right corner of the page, will close the page without saving the information entered in step 1 and step 2.
  • Save Changes: This option is available only after opening an existing API to edit, and it is activated only after changes are made to the page. Click Save Changes to save the changes you made in this page. A popup window displays a message giving you the option to Save Changes or Discard Changes. Click Save Changes to save the changes you made, close the popup, and return to the Summary & Confirmation page. Click the Discard Changes link to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page.
  • Discard Changes: This option is available only after opening an existing API and only after you have made changes to the page. Click the Discard Changes link if you do not want to save the changes you made to this page. A popup windows displays a message giving you the option to Save Changes or Discard Changes. Click Discard Changes to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page. Click the Save Changes link to save the changes you made, close the popup, and return to the Summary & Confirmation page. 

Step 3: Assign Security Profiles

There are three 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 additional information.

  • Select: Click on Select to display a list of existing security profiles. Select the appropriate Profile from the list.

  • Create New Profile: If an existing profile is not appropriate, click on the Create New Profile link to open the Security Profiles page and create a new profile (see Security Profile Creation and Configuration). When you save the new profile, you are returned to step 3 to assign the new profile to the new API you are creating.

  • Assign Profile: This button is activated once a security profile is selected. Click Assign Profile. The profile assignment displays in the table at the bottom of the page.

  • Repeat step 3 to assign multiple security profiles to the API. Once completed, all assigned profiles display in the table. Select the delete icon  to the right if any of the settings are incorrect and repeat step 2 with the correct information. See Harmony API Security for additional information about assigning multiple profiles to an API.
  • Next: Select Next to continue to step 4.
  • Cancel: Selecting Cancel at the bottom of the page or selecting the close icon  in the top right corner of the page, will close the page without saving the information entered in step 1, step 2, and step 3.
  • Skip this Step: If a security profile has not been selected and assigned, selecting Skip this Step will 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 automatically anonymous and publicly accessible by default at the time it is published. 
  • Save Changes: This option is available only after opening an existing API to edit, and it is activated only after changes are made to the page. Click Save Changes to save the changes you made in this page. A popup window displays a message giving you the option to Save Changes or Discard Changes. Click Save Changes to save the changes you made, close the popup, and return to the Summary & Confirmation page. Click the Discard Changes link to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page.
  • Discard Changes: This option is available only after opening an existing API and only after you have made changes to the page. Click the Discard Changes link if you do not want to save the changes you made to this page. A popup windows displays a message giving you the option to Save Changes or Discard Changes. Click Discard Changes to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page. Click the Save Changes link to save the changes you made, close the popup, and return to the Summary & Confirmation page. 

Step 4: Summary & Confirmation

The Summary & Confirmation page displays all the settings and selections made within step 1 through step 3, allowing you to review, confirm, and edit the information prior to publishing the API. Each section of this page corresponds to a previous step.

  •  Settings: Along the top of the page is a summary of the Settings information entered in step 1, including the API name, environment, and description.
    • The Time Out, SSL Only, CORS, and Verbose Logging options are enabled if they display a check mark  to the left. Each option that displays an  to the left is disabled.
    • Enable Debug Mode Until: An orange checkmark displays to the left of the date and time fields if debug mode is enabled. The checkbox, date, and time are blank if debug mode is disabled. 
      • You can enable debug mode within this page by clicking the checkbox. The date and time will default to exactly one hour after you enable debug mode. 
      • A popup message describes debug mode processing and the consequences of running in debug mode for a longer period of time.
      • Select Continue to enable debug mode or Cancel to disable debug mode and close the window.
      • Click in the date field to select a different date in the calendar. Click in the time field to select a different time.
    • Selecting the edit icon  to the right of the section returns the user to the step 1 page for editing. 
  • Operations: The Operations section displays the information entered in step 2 including the project, operations, methods, and response types assigned to the API.
    • Selecting the edit icon  to the right of the section returns you to the step 2 page for editing. 
  • Security Profiles: This section displays the information entered in step 3 including the profile name and authentication type for each security profile assigned to the API. 
    • Selecting the edit icon  to the right of the section returns you to the step 3 page for editing.
  • Export: This automatically exports the selected API to a file named apis-export.apk in your Downloads folder. This file can then be imported into a different environment or organization.
  • Clone: This option is available only after opening an existing API to edit. This creates an exact copy of the existing draft or published API, except for the API Name, Service Root, and Version fields. The phrase "Copy of" is appended to the beginning of the text in the API Name and Service Root fields. The text "-2" is appended to the end of the existing version. The cloned API is immediately opened in a new Summary & Confirmation window. You can rename the API, edit selected information and then Save & Publish as a new API. You can change the version of the existing API and then Save as Draft until you are ready to publish the new version.
  • Delete: Click Delete to permanently delete the API from the organization and close the confirmation page. A popup message will ask you to confirm you want to delete the API.
    • If the API was published at the time of deletion, the API is removed from the My APIs page. It is also removed from the number of APIs used against your subscription limit. 
    • If the API was previously saved as a draft, the API is removed from the My APIs page. The number of APIs used against your subscription limit does not change as the API was not accessible while in draft status.
    • Select Continue to completely delete the API. Select Cancel if you want to close the popup window and return to the Summary & Confirmation page.

  • Save as Draft: Click this button to save the information entered or changed in step 1, step 2, and step 3 as a draft version.
    • If the API was previously published, the API displays on the My APIs page in Published w/Draft status.
      • The published version of the API is still accessible and remains included in the number of APIs used against your subscription limit. The draft version of the API is not accessible and does not increase the number of APIs used against your subscription limit. 
    • If the API is new, or the API was previously saved as a draft, the API displays on the My APIs page in Draft status.
      • The API is not accessible and is not added to the number of APIs used against your subscription limit.
    • You can return at any time to edit the draft API (see My APIs).
  • Save & Publish: Click this button to publish the API. The API is live and accessible within 5 minutes when accessed with the assigned profiles and authentication methods.
    • If the API was previously published, or was previously in Published w/Draft status, the API displays on the My APIs page as Published
      • The new published version of the API overwrites the previous published version. There still is only one version that is accessible. It does not increase the number of APIs used against the subscription limit. 
    • If the API is new, or the API was previously saved as a draft, the API displays on the My APIs page as Published.
      • The API is now accessible and increases the number of APIs used against the subscription limit.
    • A popup message displays indicating the API is live:

      On the popup message dialog:
      • Copy URL: Click this link to copy the API URL to your clipboard. Paste the URL into a browser and press enter to test the API. For this example, the operation responds with JSON output: 

      • Generate OpenAPI document: Click this button to open the Portal Manager page to review the OpenAPI documentation and execute the API.
      • Dismiss: Click this link to close the popup window.
  • Cancel: Selecting Cancel will close the page without saving the information entered in step 1, step 2, step 3, and step 4

Step 5: Next Step

After selecting Save & Publish, the API is live and accessible based on the assigned security profiles and ready to be consumed by other applications and services.


On This Page

Last updated:  Dec 06, 2019

  • No labels