Migrating Apigee Developer Portals to Drupal 8

For several years, Google has leveraged Drupal as the primary tool for developer portals built for its popular Apigee Edge API platform. With the introduction of the production-ready Drupal 8 distribution in May 2019, an announcement was made that support for the D7 platform would expire in 12 months. Concurrent with that announcement we know that D7 end-of-life will occur in November of 2021. This means that many Apigee portals will need to make the move to Drupal 8 or Apigee’s integrated portals in the near future.

In this article, we will walk through the steps to migrate Apigee portals from Drupal 7 to 8. The first decision you will need to make is whether to upgrade your existing custom build or move to the new Drupal 8 kickstart distribution. To help guide this decision, let’s first take a look at what the Apigee distribution for Drupal 8 has to offer and why you would want to leverage this platform.

Apigee Developer Portal Kickstart (D8)

The Apigee documentation site has excellent instructions on how to set up a developer portal using their Drupal 8 distribution. We will take a quick look at the features that come with the newest install profile.

Apigee Kickstart Homepage screenshot

The Apigee distribution once again has a nice out-of-box experience. This time around the base theme leverages a Bootstrap base theme that makes it easy to brand and customize your site.

The content types you see will be familiar: Article, Basic page, FAQ, Forums, and a new Landing page content type. Video, images, and audio are now more appropriately Media types in Drupal 8. The SmartDocs content type is gone in favor of a new API Doc type that supports the OpenAPI format (see below).

API doc screenshot

Adding content is now more flexible in Drupal 8 with the implementation of Paragraph types. Paragraphs allow you to add different components onto the page in any order you like. See the homepage example below.

Apigee Paragraphs screenshot from Homepage

In Drupal 8, Apigee also added some new block types. Blocks are still useful for components that need to live on more than one page.

Apigee block types screenshot

The great thing about Apigee’s distribution is that it also includes sample content which makes getting set up a breeze. 

For organizations setting up a portal for the first time, leveraging this distribution is the way to go. For portals being upgraded from Drupal 7, this is more of a judgment call. If your portal has been heavily customized it might be better to move forward with a traditional Drupal 8 upgrade which we will cover under Custom Migrations. If, however, your organization’s portal previously had taken advantage of out-of-box functionality, then it makes sense to migrate content to Apigee’s D8 project which we will walk through next.

Migrating to Apigee Kickstart D8

The maintainers of the Apigee kickstart distribution have supplied a module to make migrations as painless as possible. The apigee_kickstart_migrate sub-module provides the Migrate module configuration that maps Drupal 7 content to their newer Drupal 8 counterparts. Again, this is most helpful for portals that did not heavily customize content in Drupal 7. Included in this sub-module are instructions on how to run the migrations and how to extend migrations with custom fields.

The following table shows how content is mapped from the Drupal 7 portal to Drupal 8.

Custom migrations

When would you go with a custom Drupal 8 upgrade over leveraging the Kickstart project? 

Where you run into trouble with distributions in Drupal is when you lean on so many customizations that the distribution gets in the way more than it saves time. In those instances, it’s better to stick with your own custom implementation.

The Mediacurrent team recently released the Migrate Pack module to make things easier for developers. This module has been tested against several sites and distributions including the Apigee Drupal 7 install profile.

​

The approach here would be to install Migrate Pack and the two additional Apigee modules in lieu of leveraging the distribution. The two key Apigee features you will need are the Apigee API Catalog and Apigee Edge modules. All of these projects should be installed using Composer.

If your theme was built custom in Drupal 7, then it will need to be manually ported to Drupal 8’s Twig-based theme engine. The other option is to instead borrow the Bootstrap-based theme included with Apigee’s distribution. It should be said that if the latter approach is taken, it might be better to migrate everything to the new Kickstarter rather than cherry picking the theme.

Next Steps

Apigee has very good support and documentation to get you started on moving to Drupal 8. For issues and bugs specific to the Drupal distribution, the Github project issue queue is the best place to look. The Migrate Pack module also has its own issue queue on Drupal.org should you run into problems.

Mediacurrent has logged over 100,000 hours in Drupal 8 development, many of which are Drupal 7 to 8 upgrades. We would love to work with you on your next project. 

Please visit our contact page to get in touch or hit me up on Twitter to talk more. We also have comments below to gather your feedback and questions.