To access the Portal Manager, log in to the Harmony Portal and select the API Manager card. Click on My APIs in the upper left corner and select Portal Manager in the dropdown.
OpenAPI documentation is generated In Portal Manager for each Jitterbit Harmony Custom API and for each API Proxy created within API Manager. OpenAPI documentation is not generated for OData Services.
Portal Manager provides the ability to create, customize and manage an external facing developer's portal for your APIs. Developers can access the external facing portal to discover, evaluate and consume APIs by invitation only.
NOTE: As of version 10.2, the API documentation editor has been upgraded to accept OpenAPI 3.0 documentation. You can now copy OpenAPI 3.0 documentation into the Portal Manager. You can edit, save and publish the documentation within the Portal Manager
Getting Started with Portal Manager
View the video outlining the steps to create an OData API.
View the video outlining the steps to get started with Portal Manager.
Initialize Portal Manager
The first time you access 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:
- Select Initialize Portal.
- Select the appropriate Environment from the dropdown. This environment selection determines which environment's APIs are displayed to API consumers on your 'Public Portal'.
- OpenAPI 2.0 documentation for all your existing APIs will generate automatically.
Note: Currently API Manager is limited to one Portal Manager and one public facing Portal that provides access to APIs in one environment only.
Documentation for each API displays in the OpenAPI Editor panel 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 documents for your APIs, please see OpenAPI Specification.
You can 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.) Or click on the Lock icon for the specific API you want to test and enter the required credentials.
- Select Get.
- Select Try It Out.
- Select Execute.
- The API executes within the Portal Manager and the operation responds with the JSON output.
Customize Portal Manager
Customizing the Portal Manager determines what is visible to consumers on the external facing developer's portal. You can brand the portal by uploading your company logo and changing the title using the OpenAPI Specification. Provide all the information your developers need to interact with your company by including phone numbers, email addresses and links in your documentation.
Upload Your Company Logo
Customize your developer's portal with your company logo.
- The logo must be in a .JPG or .PNG file format.
- The logo file must be 120KB or LESS.
- Within the Portal Manager, click on the BROWSE LOCAL FILES link in the upper left corner of the page.
- Select your logo file and click Open.
Your company logo now displays in the upper left corner of the Portal Manager and in your developer's portal. Click on the View API Documentation link in the upper right corner to view the logo in your developer's portal. Click on your browser back arrow to return to Portal Manager.
Customize OpenAPI Documentation
When you initialize the Portal Manager, the title of the page is Jitterbit. You can customize the title and the text that will display in your developer's portal using OpenAPI 2.0. Go to OpenAPI Specification to learn how to use the specification and customize your developer's portal by entering the title, description, termsOfService, contact, license, version and additional information that will enable your consumers to interact with your company and successfully work with your APIs..
Once you have entered your custom OpenAPI specification, the title, text and links will display on the right side of the Portal Manager and in your developer's portal. Click on the View API Documentation link in the upper right corner to view the title and additional custom information in your developer's portal.
Missing Documentation for New APIs
Warning: When you publish a new Custom API or API Proxy, the new API will not display in the Portal Manager or your developer's portal. To display the documentation for the new API, you will be required to regenerate the OpenAPI documents. This will overwrite any custom documentation that you have entered in all your API environments. Follow the steps below to preserve and restore your custom documentation.
Regenerate Docs & Publish
Warning: Selecting Regenerate Docs & Publish will overwrite any custom documentation that you have entered in all your API environments. Follow these steps closely to preserve and restore your custom documentation.
- Highlight and copy your custom specifications in the OpenAPI Editor panel on the left side of the page and save them into a text editor.
- Click Regenerate Docs & Publish in the upper right corner of the page.
- A popup warning message displays outlining the consequences of continuing. If you have made a copy of your custom documentation, click Continue. Click Cancel if you do not want to regenerate your documentation.
- The documentation in the OpenAPI Editor panel reverts to the original title (Jitterbit) and version (1.0.0), and all other custom documentation is removed.
- Paste your custom specifications into the OpenAPI Editor panel.
- Select Save & Publish in the upper right corner of the page.
- Your customized documentation will be refreshed in the Portal Manager and in your developer's portal.
Invite Developers to Your Developer's Portal
Your developer's portal is accessible to users only by invitation and requires the developer to create a username and password to gain access.
Add the developer as a Member of your Jitterbit Org. Assign the developer to a role that provides ApiConsumer and Read permissions only.
TIP: Complete instructions for setting up your organization, roles, members, and ApiConsumer permissions can be found under Organizations within the Management Console documentation. See the steps in the Environments page to assign the role to an environment and assign the View Logs and Read permissions.
- The developer will receive a welcome email directly from Jitterbit and will be instructed to click on the link to register the account. The developer will be required to enter their name and phone number, create a password and secret question answer, and enter the registration code that is sent in a second email from Jitterbit.
- You will be required to send the developer the URL to access your developer's portal. On the Portal Manager page, select Portal from the dropdown in the upper left corner of the page to view your developer's portal. Copy the URL.
- Send the URL to the developer to access your developer's portal.
- The developer will be required to enter their email address and the password created during registration to log in to the developer's portal.
The developer will also be required to enter the appropriate credentials before executing an API that is assigned a Basic or OAuth security profile.
NOTE: Internal API App developers may need Execute and Write permissions assigned to the API environment in addition to View Logs and Read permissions. These permissions will allow members to access API Manager directly, create and edit security profiles, create and edit APIs, and access to some functionality in Management Console. We suggest creating separate roles for internal and external API App developers to accommodate the different levels of security and access required.
- OpenAPI Specification.
- Introducing the OpenAPI Initiative
- API Handyman - OpenAPI Specification Tutorial
- Getting Started With Swagger
- Pet Store Swagger Example
- Swagger IRC
Last updated: Nov 08, 2019
- No labels