Skip to end of metadata
Go to start of metadata

Introduction

My APIs is the landing page where you create, edit, clone, delete, publish and manage all of your APIs.

  • View all of your APIs within one page in a card view format that includes the API name, description, lifecycle stage, last edit date and time stamp, edit by username. Hover over each card to view the API name, short description, version, View/Edit button.
  • Create and publish Custom and OData APIs following one easy 4 step process. Set the timeout or SSL only option and enable CORS or debug mode.
  • Clone an existing API to create a new version of the existing API or create a new API with the ability to save it as a draft until you are ready to publish.

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. 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 an API.
  • A minimum of one project that contains at least one functioning workflow or operation is required to create an API.

Getting Started with API Manager

View the overview video and preview the steps to create a custom API.

 Click to show or hide video

Custom API Operation

For this guide, we are using a simple operation that was created using the Design Studio.

 Click to show or hide the 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 hamburger 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 Create & Publish New 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.

 Click to show or hide the settings

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

      Known Issue: Including a period at the end of your Organization Name (e.g. Inc. or Ltd.) will cause the API service URL to be invalid. To edit the Organization Name, see Organizations.

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

    Warning: OpenAPI requires CORS to be enabled in order to execute your APIs within the Portal Manager and in the Developer's Portal.

     Click to show or hide settings

  • 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.  
  • Select the Calendar icon to the right of the date/time 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 popup calendar.
    • Click in the Hours field and use the +/- symbols to adjust the hour and minutes.
    • Click Set Time and click Done.

       Click to show or hide settings

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

    NOTE: The Service URL (shown here as https://JitterbitTRIAL150.scout.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://JitterbitTrial150.scout.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. 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. 
  • 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.

     Click to show or hide the settings

  • 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 orange Trash Can 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 to continue to Step 4 without assigning an 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 only Google as the 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.

     Click to show or hide settings

  • The profile assignment displays in the grid at the bottom of the page.

     Click to show or hide settings

  • Repeat this step to assign multiple security profiles to the API.
  • Select the orange Trash Can 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 of 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 orange pencil 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 of the settings on the Summary & Confirmation page have been corrected and/or verified, select Save & Publish.
 Click to show or hide Summary & Confirmation with additional instructions
  • 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 "x" to the left is disabled.
  • Selecting the orange Pencil 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 orange Pencil 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 orange Pencil 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


  • .Select the API URL at the top of the page for a quick test. For this example, the operation responds with JSON output:

     Click to show or hide the JSON output

  • Select View/Edit Documentation to open the Portal Manager.

Additional Options in Step 4

Additional options are available to save the API as a draft as well as to clone, delete or export the API to an API Pack (.apk file).

Export

  • Exports the API to an .apk file, which can then be imported into a different environment or organization.
  • Selecting Export prompts you to save the API Pack in your default download folder. The default filename is apis-export.apk.

    NOTE: When importing an API to an environment or organization, the underlying source project and operation must already exist in the environment and organization.

Clone

  • Creates an exact copy of the existing draft or published API, with the exception of the API Name and Service Root. The phrase "Copy of" is prepended to the text in these 2 fields.  
  • Selecting Clone immediately opens the cloned API in a new edit 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

  • A popup message asks if you are sure you want to delete this API. 

  • This action deletes any draft changes as well as removes the API from the current environment. 

  • Select Continue to completely delete the API. If the API was previously published, it is no longer accessible and is removed from the count of APIs used against your organization's subscription limit.

Cancel

New API not previously saved as a draft or published:

  • Selecting Cancel saves the API as a draft.  The API card displays on the My APIs page, and DRAFT displays clearly below the name of the API.  As a draft, the API is not accessible and does not increase the number of APIs used against your subscription limit. 

API previously saved as a draft:

  • Selecting Cancel returns the API to draft status. The API remains available on the My APIs page for further editing or to publish at a later date. As a draft, the API is not accessible and does not increase the number of APIs used against your subscription limit. 

Previously Published API:

  • Selecting Cancel saves any changes made during the session as a draft.  The published API remains unchanged and accessible.  The card view of the API on the My APIs page will indicate the API is PUBLISHED W/DRAFT below the name of the API. You can publish the changes saved in draft mode at a future date. 
  • To edit or publish the API at a later date, hover over the API card, select View/Edit, make any required changes and select Save as Draft to remain in draft status or Save &Publish to publish the API.

Save as Draft

New API not previously saved as a draft or published: 

  • Selecting Save as Draft saves the API as a draft.  It is available on the My APIs page, and DRAFT displays clearly below the name of the API. As a draft, the API is not accessible and does not increase the number of APIs used against your subscription limit. 

API previously saved as a draft:

  • The API remains in draft status and available on the My APIs page for further editing or to publish at a later date. As a draft, the API is not accessible and does not increase the number of APIs used against your subscription limit.  

Previously Published API:

  • Selecting Save as Draft will save any changes made in the session as a draft.  The published API remains unchanged and accessible.  The card view of the API on the My APIs page will indicate the API is PUBLISHED W/DRAFT below the name of the API. You can publish the changes saved in draft mode at a future date. 
  • To edit or publish the API at a later date, hover over the API card, select View/Edit, make any required changes and select Save as Draft to remain in draft status or Save &Publish to publish the API.

Save & Publish:

New API or API previously saved as a draft:

  • The API is live and accessible based on the assigned security profiles. The API increases the number of APIs used against your subscription limit.

API previously saved in PUBLISHED W/DRAFT status:

  • Selecting Save & Publish publishes the saved changes on the existing live API. The API remains live and accessible based on the assigned security profiles.  An API that is in published w/draft status is already included in the number of APIs used against your subscription limit. Publishing the changes to the existing API does not change the number of URLs used.

On This Page

Last updated:  Oct 29, 2018

  • No labels