We outlined in our previous article the key features that make Drupal 8 a good starting point for a developer portal. These options lead to further questions - Where do you start? What is available for an easier or faster ramp-up? How can I integrate API management tools? In this article we address what is available for use if you use Drupal 8 for your developer portal. You can of course use Drupal CMS with any API management gateway/platform. This article uses Apigee as a key example.
- Apigee Edge Integrated Portal
- Drupal (Drupal Core, Modules, Distributions - Apigee Developer Portal Kickstart)
- Devportals as a Service (Pronovix Developer Portal)
- Comparison of Devportal Solutions
Apigee Edge Integrated Portal
Apigee provides two options for getting started: the Apigee Edge Integrated Portal and the Apigee Developer Portal Kickstart Drupal Distribution. To understand the latter, we will need to explain Drupal in relation to its modules, themes, and distributions.
Apigee offers a ready hosted solution for setting up a basic customizable website that integrates with a subset of features available through their API management platform.
- Customize design elements via SCSS style sheets and personalized branding
- Markdown and HTML to compose content
- Create pages using page editor
- Add menus for navigation
- API Documentation
- Self-service registration for developers to build apps using your APIs
- Access control to portal content and APIs
- Analytics via Google Analytics and custom analytics tracking
- Advanced customizations (customize domain, custom registration fields, extend portal using scripts, configure your email)
This is an ideal option for businesses looking for a simple developer documentation or marketing site with a few easy to document APIs and minimal documentation. Monetisation, load balancing, API revisions, and more complex documentation structures are not available.
Up until May 2019, Apigee promoted migrating from the Apigee Edge Integrated Portal to an Apigee Drupal 7 developer portal. This has been phased out and they now recommend sourcing an integrated developer portal using Drupal 8 for more complex needs.
Drupal 8 is an open source Content Management System (CMS) that was developed in the last two decades by a diverse community of developers to provide the tools to build reusable, versatile, structured features and content that dynamic web experiences require. Drupal is above all a framework from which a developer portal can be structured.
Drupal 8 is supported by a community of dedicated contributors who innovate to expand CMS functionality and usability experience (UX) by developers, site administrators, and end users. At the same time, web agencies, development shops, and our own development team at Pronovix work exclusively within the Drupal framework while maintaining proprietary projects that are not publicly available to the community at large.
Drupal can be described as the sum of its: Core, Distributions, Modules, and Themes.
This is Drupal ‘out of the box’. Downloading and installing will give you a blank website that contains all of the basics to create a content site. As an official release, it comes bundled with what are considered the most essential modules and themes. With every major Drupal release, architectural improvements are released, and some of the contributed modules that were most popular or useful in the prior release are integrated into the core product release. What this means is that with each subsequent release of Drupal (5 to 6, 6 to 7, 7 to 8) tools and elements created for utility are incorporated and thereafter fully supported. Because of this, each version of Drupal is improved on the previous and benefits directly from those community built and industry perfected modules.
Simplified illustration of Drupal Core
“There is a module for everything and if there isn’t, then build one.”
As Drupal is built to be extendable through a modular architecture, members of the Drupal community constantly add contributed functionality in the form of modules and themes that have been registered with drupal.org. These modules and themes are maintained and supported by the community. Not all modules are built with the same quality of engineering, so they are not equal and standards vary from usability to response time for support or issues. The functionality the module provides is heavily dictated by the module creator and maintainer; however, contributors will attempt to make it as generic and reusable as possible. Modules and themes can also be built as a result of collaborations between companies within the community that discover they have shared requirements.
The key to choosing the right modules to use is to ask:
- What functionality do I need?
- Is there a module for it?
- Is this module stable and secure?
- How many issues are in its queue and are they issues that will affect my use?
- Is the issue queue and module actively updated and maintained?
- Are other users adopting this module for their projects?
Examples of API management related modules:
- Developer Portal
- Apigee Edge
- UI for Apigee Edge
- Apigee API Catalog
- Open API
- Swagger UI for OpenAPI UI
- Swagger UI Field Formatter
With all of these modules, you can download and install them to your Drupal instance and ascertain if the functionality is what you need. In some cases, multiple modules may serve identical purposes but one may be better for your purpose than another. Once in use, you can modify contributed modules to meet your unique needs and provide any changes or extensions as patches back to the maintainers of the module for them to consider for addition. It also does not hurt to make feature or support requests to the module maintainers for assistance.
In all of this, modules can also be created or used in a proprietary fashion where the module is not registered with drupal.org and/or takes on its own life within a development project. Because a module is a building block, it’s final destination, configurations, interactions with other modules, and usage within a final project is flexible.
Distributions arose in Drupal as a result of developers wanting to be able to create multiple sites that fell into the same general category rapidly and consistently. As an example, the Commerce Kickstart is possibly the most recognized and widely used distribution on Drupal as a quick means to launch online stores. Distributions contain Drupal core, contributed modules, themes, and predefined configurations. As of the writing of this article there are 1,325 distributions of Drupal available from drupal.org.
A distribution is most often used as a rapid means of testing a specific use case, e.g. Apigee Edge integration. As with modules you may need to try a few distributions before finding the right fit for your needs. Further, using a distribution as a basis for your developer portal will result in an upstream dependency on the distribution maintainers for security and updates. It is vital to ensure that any distribution used in this manner is well maintained and for this reason we recommend against it. A distribution is not intended to be a complete solution in itself, but can save much effort if your use-case is well aligned within the distribution’s goals and if you are willing to accept their constraints, e.g. fixed theme, content structure or layout, or ability to change font and colors.
Simplified illustration of a Drupal Distribution
So what can you get out of a distribution?
You can decide which modules form a good basis to work in collaboration with others to outline the internal structure desired for your Drupal based developer portal.
Apigee Developer Portal Kickstart
This distribution is great for evaluating how the Apigee Edge module integrates with Drupal 8. The Kickstart installer guides a user for information to instal Drupal 8 core, configure a connection to Apigee Edge, and customizations to the theme.
- Developer Portal homepage
- API Catalog page
- “Getting Started” page
- Modules for FAQ, Blogs, and Forums
- API documentation content type
- 16 pages with preloaded content for demonstration
- API doc landing page with demo content and vocabulary
- Customizable site theme
This distribution provides a basic developer portal that is integrated with Apigee Edge. You will need some basic Drupal knowledge to set up this distribution. Depending on your knowledge, installing this distribution may not be trivial. Once installed, you will still need to configure your site and potentially download additional modules to account for additional feature requirements such as adding user access controls and SSO (single sign-on) integration, more complex page layouts, and user experience improvements.
Devportals as a Service
So far we have answered the question of "With what do you start?" and "How can I integrate API management tools?" Now we will answer the question of "What is available for an easier or faster ramp-up?"
This is where Pronovix shines - for an immediate understanding of the magic of Apigee and Drupal working in concert, we are happy to schedule a short demo for you.
A Drupal 8 CMS as a backbone for your devportal can be:
- built & maintained in-house by your own devs
- built & maintained by a Drupal agency
- immediately up & running as a pre-built Devportal as a Service
There are a number of Drupal Web Agencies that can take your list of requirements and create a solution to handle your developer portal needs based on their knowledge of Drupal, modules, distributions, and usage. Most web agencies will also address theming based on your company’s specifications. With an outsourced developer portal, updates and new features or customizations will depend on the relationship and agreements with the company or internal team providing licensing, support, and maintenance.
Pronovix Developer Portal
We moved from being a Drupal agency, est. 2005, to specializing in creating developer portals in 2015. Our deep interest and active participation in the documentation and developer experience communities meant we had a front seat to advising on and building initial Drupal based portals focused on documentation. We are now part of the success of 40+ API developer portals across a multitude of industrial sectors.
We offer a developer portal product built with Drupal 8 and continue to support and contribute to many of the modules that are listed above.
The Pronovix developer portal is perhaps the fastest and easiest means of getting to ‘done’ with a developer portal using Drupal 8. Our portals are standardized with best practices established through both our independent research and our customer's feedback.
Our engagement with new customers begins with a UX information gathering phase about how the devportal will be used and by whom. Based on the workshop feedback, we configure the features in the devportal to fit your specific business objectives, content, and users. For your live devportal, we also provide the hosting, maintenance and support so that your team can focus on your API products and their documentation.
- UX process to get started and align to how the site will be used
- Ready-to-use hosted, supported, and maintained solution
- Extended API Reference Catalog
- Extended API Documentation including release notes, supporting documentation, use cases, sandbox “Try it out”, code visualization and example code
- DocOps via Continuous Integration/Continuous Deployment (CI/CD), commonly referred to as “Docs-as-Code”
- 30+ premade responsive page templates that can be adjusted according to your branding and design styleguide
- Page-building tools for landing pages and other custom pages
- Advanced Search
- User Guide
- Change management for legal documentation
- SSO Integration
- Flexibility in API Key management (e.g. Apigee Edge)
Support & Custom work
We provide support packages to ensure a dedicated team is addressing your needs while maintaining the back end and site’s security. We also have design and UX teams and pride ourselves in optimizing developer experiences.
Using the Pronovix developer portal as a starting point, our team can address additional feature needs that may arise such as unique graphic design, information architecture, content creation, content review, additional 3rd party integrations, and any other kinds of business logic that may be required.
We are also interested in crowdfunding development of new and complex features that are made more robust by their application to different customer needs. This both reduces the cost associated with custom development and results in continuous innovation and product growth.
Comparison of Devportal Solutions integrated with Apigee
|Apigee Edge Integrated Portal||Apigee Developer Kickstart Distribution||Pronovix Developer Portal|
|Apigee Edge Integration||✔||✔||✔|
|Apigee API Catalog||✔||✔||✔*extended|
|User Guide/"Get Started"||✔||✔|
|Built-in integrated devportal (Display stored APIs, monetization, load balancing)||✔|
|DocOps via CI/CD||✔|
|Addition Features and Product Updates||✔|
|Hosting, Support, and Maintenance||✔||✔|
*Only solutions mentioned in this article are compared.