Article By: Tiffany Kongpachith
CA/Broadcom API Developer Portal (API Portal) allows API owners to control how APIs are published, enables consumers to discover what services are available, and helps operations teams monitor API performance. API Portal simplifies API integration and discovery for developers and provides them with access to enterprise data to build apps fast. Relationships with developers, partners, and third parties are easily managed, and analytics provide valuable operational data. The new information provided in this documentation was provided at Broadcom Canada Partner APIM Workshop 2019.
API Developer Portal v3.5 (Classic) Capabilities
Some of the API Developer Portal Successes under the 3.5 Classic version were:
- Numerous Partners with CA/Broadcom since 2011 – The Level.
- API Documentation updates.
- External Partners with API Management.
- API Gateway integration with publishing.
- API Gateway flexibility with authentication schemes
However, some of the API Developer Portal Challenges faced under the 3.5 Classic version are:
- High availability.
- Multi-cluster Management.
- CMS and WebDev knowledge.
- Deployments between environments.
3.5 Portal (Side): Publishing APIs
The Classic Portal 3.5 in terms of publishing APIs have distinguishing capabilities such as:
- Ability to ‘Add New +’ to publish API and Manage the APIs by URL and API Name.
- From the API Gateway side, within the Policy Manager – Publish Web API by Name, No Target URL, URI of API.
- Assertion necessary to add to new API would be the ‘Set Portal Managed Service’ assertion.
- Site settings > Manage Appearance – this can include custom code for appearances and add CSS configurations.
- With the Lab – to create an Organization, User Admin perspective to create XYZ.
- Create Portal and Gateway Published APIs from Dashboard > APIs > Add New and input the necessary fields.
- The Current Process of Managing Customer Support – support cases on the rise for Portal Migration and Engagement Process Not Scalable at the time.
API Developer Portal 4.X (Enhanced Experience) Capabilities
Some key enhancements introduced during the transition from 3.5 to 4.X API Developer Portal are:
- API Plans
- Enhanced API Search
- User Search
- SMTP 2-Way SSL
API Developer Portal 4.X Features
As of 4.4, which was released in December 2019, the API Developer Portal 4.X is equipped with a range of enhanced features, including:
- Visibility of APIs, more fine-grain view.
- Swagger / OpenAPI 3.0 Markdown.
- Analytics reporting.
- Multi-tenancy via enhanced tenant provisioning APIs.
- SOAP Support.
- Integrated API Monitoring (Runscope)
- Portal Helm charts deployments
- Subdomain as a hostname (upon install)
- Multiple proxies to be hosted on Portal.
- Analytics – NOT Jarvis anymore! Druid-based now.
- Kubernetes can bring its own Kubernetes environment to deploy and scale the Portal – current SAAS has 40 tenants, 60 Gateways, 2500 APIs, 2000 applications on a single instance. The plan is to have multiple stacks to double load by early Summer of 2020.
For Content Management:
- Can upload an HTML for a custom page setting (upload Page Bundle)
- This was no accessible in version 4.3
For Adding a Proxy to an API:
- Navigate to Publish API > Proxies > Add
- It will be automatic.
- On-Demand (on the CI/CD – for future state)
- Proxy Details > Proxy Name = [Enter a Proxy Name]
- Organization Details (which are Assignments) = Environment (i.e. Dev, Staging, QA, Production, etc). This can be seen in the Deployments tab.
- Also have permission to redeploy, undeploy, or deploy new proxies to the API.
For API Explorer:
- You can now select an Application or API Key.
- Everything will be under /api-management/1.0/xxx
- Specs contents are signified as “assets” now to pass Swagger contents into JSON contents.
For API Key and Client Secrets:
- The API Key = Client ID dealt with OTK/OAuth.
- Cannot change the API Key.
- You can ONLY change the Secret (Password).
- Able to regenerate keys.
- For Applications, can regenerate multiple keys for the Application.
- Able to delete or recreate new keys.
- Can click an API and determine what Proxy to assign to.
- Can view the status (Enable/Disable)
- Can view the details – such as Restman or the results of the bundle.
- Can redeploy or undeploy an API.
- Can view the Type (Auto/Demand/Scripted) and view under the Deployments Tab.
Different Tabs in the Developer Portal:
- Swagger.io (REST contents)
- Most documentation is Swagger-based.
- Have a Markdown (Editor) – managing contents (in version 4.5)
- Have standard tools.
- Documentation Tab > view and manage the API with the (+) and Edit button to edit the API if not, contents are within Swagger.
- You can specify the Title and Publish.
- CMS for API Documentation.
- UI Customization – a powerful tool for custom Content Management.
- Able to create custom Tag – seen on the API Page and can filter now by Tags on APIs.
- Or within the Edit API screen, can view under the Tags column.
- Organization to manage API.
- Can manage ONE organization for the API.
- Public, implies that anyone (from all Organizations) can view the APIs.
- Private, implies only one specific Organization (i.e. My organization) is able to view the APIs.
- Restricted, implies specific Organizations can view specific APIs that they are allowed to view.
API Owner Permissions:
- Open, implies that all users in the Organization can edit the API.
- Restricted, implies that only specific users are allowed to edit the API.
- A user must be an API Owner if selected in order to edit any API.
UI Customization with the API Hub:
- Customer’s Developer console.
- Enriches content and documentation.
- Localization support.
- Engage API Publishers with customers in onboarding/discovery of APIs as a part of the API Program.
- Built on ReactAdmin as a part of the API Developer Portal
- A new UI framework.
- Modern program language.
- Easier customization and branding.
- Some key features: Authentication and Account Registration and Account Management, able to search API and customizable API documentation, discovery and testing API with Swagger Specs.
- Out of Scope will be the Analytics, and versioning of CMS (custom markdown content).
- Static and dynamic pages.
- Public and Private pages.
- Branding and marketing messages.
- Theme customization.
- Rich documentation for markdown, attached files, and Swagger.
- Custom content for applications and the Home Page.
- Wiki-blog-like content for viewing.
- Roll-out date for this will be in April of 2020.
- Referential implementation consists of 12-14 pages.
Analytics Improvements from Classic to Enhanced
With version 4.5 of API Developer Portal rolling out, the analytics page will now become customizable. The recommended specs for deploying the Analytics include to give at least 64 GB of memory (RAM) for production, a 99% disk reduction, roughly 400 GB of the Analytics stack, and around 26 TB of the Jarvis stack. This is a huge, reduced disk consumption, a significant reduced memory requirement, and an increase in ingestion.
- 30% RAM consumption reduction.
- 12-16 gigs (GB) of Memory.
- 5x more of Real-Time Ingestion improvements.
- 100-500M tpd.
Classic Portal 3.5 Migration:
There are significant changes in migration between the Classic Portal 3.5 and the 4.X Portal.
The tool’s concept is to create copy as close as possible using the Portal API. It will not make assumptions, but instead, will report errors. The Gateway strategy, however, is a parallel scheme keeping Portal 3.5 to the Gateway, as well as an in-place-reassociation, making it easier to manage large clusters.
The Migration UI Tool (Classic Portal 3.5) can be found as:
Actions to Perform for the Migration (3.5):
- Analyze Only.
- Analyze and Migrate – where you define the Public URI, Token Endpoint, API Key, Shared Secret, or Skip Rejected Applications? Option
- Notify a user to its account activation email.
- Download Portal Entities.
- Download Portal Entities + Metrics Data
- Don’t Download Anything
Once all configurations are set, select the Migrate button to begin migration. Before executing the migration, the user MUST resolve errors.
Things to Check for in a Stable Environment during Classic Portal Migration:
- All requests are empty; cannot migrate entities in a Pending state.
- Reject applications that do not show in the Administrator’s Request Queue; this is skipped during migration.
- Any entity is in Disabled state (not required approval) will not be migrated.
- Check the TechDocs for prerequisites to be checked off for Classic Portal 3.5 and APIM Portal.
- Parallel gateways are enabled.
- Network availability, if there is an interruption then the migration process will fail and stop everything. Using the tools such as Classic Portal, API Explorer, APIM Portal API, and Gateway Migration Utility (GMU).
4.X Portal Migration
Some key changes and features have been provided in this new API Developer Portal 4.X version and beyond. Publishing an API now has the capability to put the API into a Disable or Unpublish state. Ensure that the APIs are in one of these two states before migrating.
Some non-migratable entities are:
- Dashboard widgets, messages.
- Account Plan API associations.
- Monetization data.
- WSDL files for SOAP APIs.
- Data APIs (migrate as REST APIs).
- API Owner groups.
- User with NO roles – Admin, API Owner, Organization Admin, Developer
- Local database user password and user avatars.
- Custom fields for registration.
- Custom fonts (CSS styling).
- Site setting entities – emails, password policies, etc.
- Translations for public entities (no languages other than English).
- Metric data (work-around available).
Although, certain conditions require data conversion like:
- API Plans being enabled manually on the tenant to be migrated.
- Or Classic Portal 3.5 API Plans allowing more time frame options, rolled up to amount per day.
- The Application Platform field will become a custom field on the APIM tenant.
- Additional OAuth fields may be collected for APIs.
- Portal published APIs will have additional protection data migrated as a policy template.
- Custom field types will be converted into test or a select input option.
- Custom field/names may need to be prompted for a new value.
- Theming data will require approval for classic anything/styling or default APIM styles.
- Theming data will not allow named color values (ex: maroon, olive green, etc).
- Original data on Classic Portal is preserved.
There is a new export package which is an error-free analysis tool.
- This includes JSON file of all migratable portal entities.
- Publicly available HTML pages.
- CMS resources directory which contains CSS styling, images galleries, API doc files, and optionally metrics data.
Some ways to handle errors are:
- Check the TechDocs charts for known errors.
- Require checking APIs in the Policy Manager.
- Some errors cannot be connected by the Portal Admin.
When executing the migration with the Migrator, check for the following:
- Notice errors highlighted in red.
- Notice when the migration has stopped.
- Notice a little red box with a list of numbers of errors that are marked in red.
- Changes that have occurred where Requests are shown in Registration and are able to Approve them (APIs).
- Private APIs can now be added.
- Custom fields now show a hashtag field and can now enter a value without the (#) symbol.
- API Service UUID is preserved now.
- API Keys and Secrets are preserved now.
- Lastly, entities (EULAs, Plans, Organizations, Users, etc) are preserved now.
Lastly, please make sure the UUIDs match, the Application API Keys match, and Account Plans have the same rate limits. If the migration was successful, then the APIs will appear in the Publish > APIs section and will be highlighted in green indicating that they are in an Enabled state.
Summary of the Differences Between API Developer Portal 3.5 and 4.X
The above information was relayed at a Broadcom Partner Workshop for API Management in Broadcom Canada. This information describes API Developer Portal from the start (Classic Portal 3.5) to advancements made from 3.5 to 4.X and future releases. Several changes were made to differentiate the Classic Portal from the Enhanced Experience Portal, including how to publish APIs, new features in 4.X compared to Classic, improvements for Analytics, and migration methods.Looking for additional information regarding Broadcom API Developer Portal? ISX Consulting is an elite IAM security firm that offers boundless expertise in a range of cybersecurity and business process services, including API integration. Take your interoperability to the next level, and contact an ISX consultant today.