Spoiler alert: Very easy with Apiboost

Apigee’s Integrated Portal is a good starting point for organizations that just need to get their API documentation online as simply and quickly as possible. However, at some point most organizations find they need to migrate their APIs, associated content, and users to a new platform to achieve their overall business and efficiency goals. The challenge with this migration is that there are no available official tools or documentation on how to do a migration. Until now!

First we’ll cover the process to migrate from Apigee’s Integrated Portal to a generic third party platform. After that, we’ll discuss the migration to the Apiboost API platform.

Please note that Apigee’s API calls listed below can change at any time since they are not officially supported by Google for external consumption. Also there is no officially supported documentation for these APIs.

What can be migrated?

Information in Apigee’s Integrated Portal can be broken down into the following types:

• Pages – Generic HTML content pages.

• APIs – API Documentation including descriptions, API Specification files, and links to API Products in Apigee.

• API Categories – Simple terms used to categorize your APIs

• Teams – Optional Beta feature that enables developers to create teams to collaborate on applications

• Audiences – Access controls that limit APIs or content to select developers or teams.

You’ll notice that we did not list developers, developer apps, or team apps here as items that can be migrated. Developers, developer apps, and team apps are all stored in Apigee and will remain accessible when your users log into the new portal with their email address. Developers will retain access to all of their apps when logging into the new portal with the same email address that they used on the Integrated Portal. Likewise, team apps are associated with a team service developer account in Apigee. Team members will retain access to their team apps as long as your new portal solution supports teams. Note that not all portal solutions support teams in a way that is compatible with the Apigee’s Integrated Portals. Happily, Apiboost is fully compatible with migrating your teams, their membership, and apps.

How to migrate from the Integrated Portal to a third party.

Like any migration, the process here is one where you:

• Export data from the Integrated Portal into a usable format.

• Clean/modify the exported information so that it can be imported into the new portal.

• Import the data into your new portal.
  

Exporting data from the Integrated Portal

The process to export data from the Integrated Portal involves impersonating an active logged-in administrative user on the portal to crawl the portal, extract data from each page, and write that information to one or more files.

User Impersonation

To impersonate a user, you first log into the Apigee Management Console with a user account that has administrator permissions on the portal that you want to export. You’ll then need to copy the request headers, particularly the cookie settings, from the browser into whatever tool that you’ll use to crawl the site. We’ll be using Postman in these examples.

• Log into the Apigee Management Console and visit the portal admin UI for the portal to be migrated

• Open the Developer tools of the browser, go to the Network Tab and look for an XHR/JS request to the portal

• Copy the Request Headers from the browser developer tools and paste them into the headers area in Postman. You’ll need to do this one-by-one unfortunately. The key headers to include are:

  • Accept

  • Cookie

    • JSESSIONID

    • access_token

    • refresh_token

    • session_context

  • X-Apigee-Csrf

  • X-Apigee-Org

NOTE: The cookies and X-Apigee-Csrf options are fairly short-lived, so you may need to periodically update these as you’re exporting data.

Available APIs for exporting data

You can now start calling Apigee’s Integrated Portal APIs to extract data. Below is a summary of the available APIs. To export your content, you need to iterate through all of these API calls and download the responses.

Getting the base URL

The base URL in the following API calls depends on your version of Apigee. But generally take the form of:

Apigee Edge: https://apigee.com/portals/api/sites/<portal-id>/

Or

Apigee X/Hybrid: https://apigee.google.com/organizations/<apigee-org-id>/sites/<portal-id>/

Available APIs

<base URL>/portal

Provides general information about the Integrated portal such as the internal ID, name, description, logo URL, etc. You will specifically need the “zone-uuid” value from this call for use in the other APIs.

<base URL>/pages

Provides a list of all content pages on the portal. The response will include the ID, name, description, and content for each page on the portal.

<base URL>/pages/<page-id>

Provides detailed information about a single page on the portal including body content and same page properties.

<base URL>/resource-entitlements/pages/<page-id>

Provides information about audience assignments and public/private flag on a single page.

https://apigee.com/consumers/api/providers/<zone-uuid>/audiences

Provides a list of configured Audiences and their membership.

NOTE: The <zone-uuid> in the URL can be found in the /portal API call response.

https://apigee.com/consumers/api/providers/<zone-uuid>/audiences/<audience-uuid>

Provides detailed information about a single audience.

NOTE: The <zone-uuid> in the URL can be found in the /portal API call response. The <audience-uuid> comes from the Audience list API call above.

https://apigee.com/consumers/api/providers/<zone-uuid>/teams

Provides a list of all teams and their membership.

NOTE: The <zone-uuid> in the URL can be found in the /portal API call response.

https://apigee.com/consumers/api/providers/<zone-uuid>/teams/<team-uuid>

Provides details about a single team and its membership.

NOTE: The <zone-uuid> in the URL can be found in the /portal API call response. The <team-uuid> comes from the list of teams API call above.

<base URL>/apidocs

Provides a list of all defined API documentation on the portal.

<base URL>/apidocs/<doc-id>

Provides details about a single API document. Same information that is provided in the /apidocs listing response.

<base URL>/specs/doc/<spec-file-id>

Provides details about an API Specification file that is attached to an API Document including the URL to download the specification file.

<base URL>/apicategories

Provides a list of all defined API Categories.

NOTE: To find the APIs that are associated with each category you must use the /apidocs call and look at the “CategoryIds” field in the response.

<base URL>/file/list

Provides a list of file assets such as images that have been uploaded to the portal.

Clean/modify the exported content

You will probably need to review and modify the exported data to format it in a way that can be imported into the new portal. This could be as simple as updating file names or as complex as performing a complete transformation of the exported data into a new format. You’ll need to review the APIs for your new portal to determine what format the content needs to be in, and then modify the exported content to align with that expectation.

Import the content to your new portal

The import process is just the reverse of the export process in many cases. You’ll need to review the documentation for your new portal to identify which API(s) can be used to import the content, and then pass your cleaned, exported content to those APIs.

You’ll then need to review and edit the imported content within your new portal to ensure that it is imported and displays correctly.

Using the Apiboost Migration Tool

Apiboost includes an optional add-on tool that simplifies the migration process into just a few minutes of work. The Apiboost Migration Tool is a Node.js console application that walks you through the entire migration process.

Step 1: Install the tool

Download the installation package and run it on your computer.

Step 2: Answer a few questions

The tool will ask you a few basic questions such as:

URL of your existing Integrated Portal.

URL of your Apiboost Portal

Credentials for your Apiboost Portal CI/CD account

Step 3: Login to Apigee and provide the information to impersonate your login

You can either configure the migration tool to be a proxy for your browser to capture the necessary information or you can manually copy/paste the headers from your browser developer tools.

Step 4: Let the tool migrate your content

The migration tool will take care of extracting all of the content from your portal and then import it into your Apiboost instance

Step 5: Review the imported content in Apiboost

Once the content is migrated, review the migrated content and make any needed updates.

The following diagram shows the relationship between the way things are named in Apigee vs. how they are named in Apiboost:

Conclusion

Migrating from the Apigee Integrated Portal can be challenging, but Apiboost’s migration tool makes the entire process almost painless. Contact us today to see how Apiboost can take your developer experience to the next level.