“Which portal should I use?” This is one of the most common questions I hear from teams implementing IBM API Connect. The answer isn’t always obvious—IBM offers four distinct portal options, each designed for different use cases. Choose wrong, and you’ll either over-engineer a simple solution or find yourself constrained by limitations you didn’t anticipate.

Let me walk you through the four options, when to use each one, and how to make the right choice for your API program.

Table of Contents

• The Four Portal Options: A Quick Overview
• Option 1: Consumer Catalog - The Zero-Setup Solution
• Option 2: Developer Portal - Configuration Without Code
• Option 3: CMS Portal - When You Need Full Control
• Option 4: Headless Portal - Build Your Own Frontend
• Quick Comparison: Which Portal Is Right for You?
• How to Choose: A Decision Framework
• Migration Paths: Start Simple, Grow as Needed
• Best Practices: Lessons from the Field
• The Bottom Line
• Resources

The Four Portal Options: A Quick Overview

IBM API Connect provides a spectrum of portal solutions, each building on the previous one’s capabilities:

1. Consumer Catalog - Zero setup, runs from API Manager
2. Developer Portal - Configuration-based customization, no code required
3. CMS Portal - Full Drupal Content Management System (CMS) for complex enterprise requirements
4. Headless Portal - Use your own custom frontend with the Developer Portal’s APIs

Let’s dive into each option with real-world scenarios to help you decide.

Option 1: Consumer Catalog - The Zero-Setup Solution

The Consumer Catalog is the simplest option—it’s not even a separate portal. It’s built directly into the API Manager, giving you instant API documentation and self-service capabilities without deploying anything.

What You Get:

• Automatic API documentation from your OpenAPI specs
• Self-service application registration and API key generation
• Basic catalog browsing and search
• Zero infrastructure or maintenance overhead
• Available the moment you create a catalog

What You Don’t Get:

• Custom branding at all
• Public-facing developer community features
• Custom content types or workflows
• Advanced portal features

When to Use Consumer Catalog

Ideal For:

• Internal API programs
• Quick proof-of-concepts
• Small-scale API initiatives
• Teams without portal administration resources
• Scenarios where basic API documentation is sufficient
• API development where developers want a consumer UX purely to test their APIs

Limitations:

• Cannot customize look and feel extensively
• Limited to basic portal features
• No custom content types or workflows
• Suitable for internal use, not external developer communities

Quick Comparison: Consumer Catalog vs Developer Portal

Real-World Scenario: Internal Microservices Platform

The Situation: A large retail company is modernizing with microservices. They need 200+ internal developers across departments to discover and consume APIs quickly. Budget is tight, and they need to launch fast.

Why Consumer Catalog Won:

• Step 1: Enabled Consumer Catalog in API Manager (literally just a checkbox)
• Step 2: Published first APIs, developers started registering applications
• Result: Zero infrastructure costs, zero maintenance overhead, instant API program

What They Gave Up:

• Custom branding (internal use, so nobody cared)
• Advanced portal features (didn’t need them)
• Public-facing portal (not required for internal APIs)

The Verdict: Perfect fit. They got 80% of what they needed with 0% of the complexity.

Option 2: Developer Portal - Configuration Without Code

The Developer Portal is where most teams land. It gives you a professional, external-facing developer portal with extensive customization—all through configuration, no Drupal development required.

What You Get:

• Professional developer portal with full API documentation
• Custom branding (logos, colors, CSS)
• Custom content types (tutorials, code samples, use cases)
• Custom fields on APIs and products
• SSO integration (OIDC, SAML)
• IBM manages infrastructure, updates, and security
• Built-in page builder for landing pages

Key Capabilities:

• Federation Support: The Developer Portal is the only portal option that can federate content from multiple API providers, allowing a single portal to display APIs from different catalogs and providers. This is particularly useful for organizations with multiple API teams or for creating unified API marketplaces. This is a core differentiator, no other portal option supports federation.

The Key Limitation: Everything is configuration-based. You can’t write custom Drupal modules or modify core functionality. For most teams, this is actually a feature—it keeps things simple and maintainable.

When to Use Developer Portal

Choose Developer Portal When:

• You need external-facing developer community
• Standard portal features meet your requirements
• You want custom branding and styling
• You lack dedicated Drupal developers
• You need rapid deployment
• You want IBM to handle updates and security

Real-World Scenario: SaaS Partner Portal

The Situation: A SaaS company needs an external-facing portal for partners and customers. They want professional branding, custom content, and SSO—but they don’t have Drupal developers on staff.

The Implementation (2 weeks):

Week 1: Branding & Structure

• Deployed Developer Portal (IBM-managed infrastructure)
• Uploaded logo, applied custom CSS for brand colors
• Created custom content types: “Tutorial”, “Code Sample”, “Best Practice”
• Added custom fields to APIs: SLA tier, rate limits, support contact

Week 2: Content & Integration

• Built landing pages with the page builder
• Configured OIDC SSO with their identity provider
• Added custom web components for interactive API testing
• Published first APIs and documentation

The Result: Professional portal that looks like it was custom-built, but it’s all configuration. When API Connect releases new features, they get them automatically. No Drupal expertise required.

What They Didn’t Need:

• Custom Drupal modules
• Complex approval workflows
• Deep enterprise system integration

The Verdict: Developer Portal hit the sweet spot—professional customization without the complexity of full CMS.

Federation: Multi-Provider Portals

One powerful feature of the Developer Portal is its ability to federate content from multiple API providers. This allows you to create a unified portal that displays APIs from different catalogs or even different API Connect provider organizations.

Use Cases for Federation:

• Multi-Team Organizations: Different business units managing their own APIs, but presenting them through a single developer portal
• API Marketplaces: Aggregating APIs from multiple providers into a single discovery portal
• Partner Ecosystems: Combining internal and partner APIs in one location

Important Limitation: The CMS Portal is tied to a single catalog and cannot federate content from multiple providers. If you need federation capabilities, you must use the Developer Portal or build federation logic into a Headless Portal implementation.

Option 3: CMS Portal - When You Need Full Control

The CMS Portal gives you complete Drupal access. This is for teams with complex enterprise requirements that can’t be met any other way—and who have the Drupal expertise to back it up.

What You Get:

• Full access to Drupal’s module ecosystem
• Write custom Drupal modules in PHP
• Modify core functionality
• Complex custom workflows
• Deep enterprise system integration
• Complete control over everything

What You Give Up:

• Simplicity (with increased function comes increased complexity)
• Automatic updates become more complex and error-prone
• Custom modules may need manual updating between CMS Portal versions

When to Use CMS Portal:

• You need custom workflows that don’t exist in standard portals
• You require deep integration with enterprise systems (ServiceNow, SAP, etc.)
• You have experienced Drupal developers on staff
• You need specialized approval processes
• Standard portal options simply can’t do what you need

Real-World Scenario: Telecom Enterprise Marketplace

The Situation: A global telecom needs a sophisticated API marketplace with multi-tier approval workflows, ServiceNow integration, custom billing, training modules with certification, and compliance tracking. Nothing off-the-shelf will work.

The Implementation (3 months, 3 Drupal developers):

Custom Drupal Modules (5 modules, ~15,000 lines PHP):

• Multi-tier approval workflow (legal → security → business owner)
• ServiceNow integration for ticket creation and tracking
• Custom billing integration with enterprise financial system
• Training module system with progress tracking and certification
• Custom notification system (Slack, Teams, email)

Enterprise Integration:

• LDAP authentication with multiple identity providers
• Custom analytics dashboard pulling from multiple sources
• Compliance tracking and audit logging
• Data retention policies

The Result: A sophisticated enterprise marketplace that does exactly what they need—because they built it themselves. But it requires ongoing maintenance: security patches, module updates, testing after every change.

The Verdict: Worth it for complex enterprise requirements, but only if you have the team to support it.

The Reality of CMS Portal Maintenance

You’re Responsible For:

• Applying API Connect fixpacks to receive Drupal security updates
• Testing all customizations after fixpack updates
• Security advisory monitoring
• Custom code compatibility with new fixpack versions
• Dev/test/prod environments
• Backup and recovery

Ongoing Effort:

• Minimum 1 dedicated Drupal developer
• Staying current with API Connect fixpacks to receive Drupal security fixes
• Regular testing cycles after fixpack updates
• Documentation maintenance

Important Note: You cannot apply Drupal security updates directly. To receive Drupal security fixes, you must stay current with API Connect fixpacks, which include the necessary Drupal updates. While IBM still manages the fixes and controls aspects like Drupal core and PHP versions, updates are more complex when compared to the Developer Portal.

↑ Back to top

Option 4: Headless Portal - Build Your Own Frontend

The Headless Portal approach gives you complete freedom to build your own custom frontend while leveraging the Developer Portal’s backend APIs for portal functionality. This is for teams who want total control over the user experience.

Important: The Headless Portal is built on top of the Developer Portal, not directly on API Manager APIs. You must deploy the Developer Portal to use this approach—you’re simply replacing the standard Drupal frontend with your own custom UI that interacts with the Developer Portal’s APIs.

What You Get:

• Complete frontend freedom (React, Angular, Vue, Next.js, whatever you want)
• Access to the Developer Portal’s APIs for all backend functionality
• Full control over UX, design, and user flows
• Ability to integrate portal into existing websites or applications
• Modern frontend tooling and frameworks
• No Drupal frontend constraints (but Developer Portal must still be deployed)

What You Build:

• Your own frontend application from scratch
• Custom authentication and authorization flows
• API documentation rendering
• Application registration and management
• Subscription workflows
• Everything the user sees and interacts with

When to Use Headless Portal:

• You need complete control over the user experience
• You want to integrate the portal into an existing website or application
• You have strong frontend development capabilities
• Standard portal UX doesn’t match your requirements
• You want to use modern frontend frameworks (React, Vue, etc.)
• You need to support unique user journeys or workflows

Real-World Scenario: Fintech Mobile-First Platform

The Situation: A fintech startup needs a mobile-first developer experience that integrates seamlessly with their existing React-based website. They want the portal to feel like part of their brand, not a separate Drupal site.

The Implementation (8 weeks, 3 frontend developers):

Weeks 1-2: Architecture & Setup

• Deployed Developer Portal (required backend)
• Designed React-based frontend architecture
• Set up Next.js for server-side rendering and SEO
• Integrated with Developer Portal APIs
• Implemented authentication flow using OIDC

Weeks 3-5: Core Features

• Built custom API documentation viewer with interactive examples
• Created application registration and management flows
• Developed subscription management interface
• Implemented API key generation and rotation

Weeks 6-8: Polish & Integration

• Integrated with existing design system and component library
• Added mobile-optimized views and progressive web app features
• Implemented custom analytics and user tracking
• Built admin dashboard for content management

Technical Stack:

• Frontend: Next.js (React), TypeScript, Tailwind CSS
• Backend: Developer Portal (deployed) with its APIs
• Authentication: OIDC with their existing identity provider
• Hosting: Vercel for custom frontend, API Connect for Developer Portal backend

The Result: A seamless, mobile-first developer experience that feels like a natural extension of their brand. Complete control over UX, modern tech stack, and the ability to iterate quickly without Drupal constraints.

What They Gave Up:

• Out-of-the-box portal features (had to build everything)
• IBM-managed frontend (they own the frontend infrastructure)
• Quick time-to-market (took longer than standard portal)

The Verdict: Perfect for teams with strong frontend capabilities who need complete UX control and want to use modern frameworks.

Headless Portal Considerations

Technical Requirements:

• Deployed Developer Portal (required backend)
• Strong frontend development team (React, Vue, Angular, etc.)
• API integration expertise
• Understanding of Developer Portal APIs
• Frontend hosting and deployment infrastructure
• Authentication/authorization implementation

Benefits:

• Complete control over user experience
• Use modern frontend frameworks and tooling
• Integrate seamlessly with existing websites
• No Drupal constraints or limitations
• Fast, responsive, mobile-optimized experiences
• Ability to iterate quickly on frontend

Challenges:

• Must deploy Developer Portal (even though you’re not using its UI)
• Build entire frontend from scratch (no out-of-the-box features)
• Longer initial development time
• Maintain frontend infrastructure
• Keep up with Developer Portal API changes
• More complex architecture

Development Effort:

• Initial: High (building entire frontend from scratch)
• Ongoing: Medium (maintain frontend, adapt to API changes)
• Requires strong frontend development skills

↑ Back to top

Quick Comparison: Which Portal Is Right for You?

↑ Back to top

How to Choose: A Decision Framework

Start with These Questions:

1. Who’s your audience?

• Internal technical teams only? → Consumer Catalog
• External developers? → Keep reading

2. What’s your customization requirement?

• Basic branding and docs? → Developer Portal
• Complete control over UX with modern frameworks? → Headless Portal
• Complex workflows and enterprise integration? → CMS Portal

3. What’s your team’s skill set?

• No portal expertise? → Consumer Catalog or Developer Portal
• Drupal developers? → CMS Portal
• Strong frontend developers (React, Vue, etc.)? → Headless Portal

4. What’s your maintenance appetite?

• Zero maintenance? → Consumer Catalog
• Minimal maintenance? → Developer Portal
• Can manage full Drupal stack? → CMS Portal
• Can maintain frontend infrastructure? → Headless Portal

The 80/20 Rule

80% of teams should use:

• Consumer Catalog (internal APIs)
• Developer Portal (external APIs with standard needs)

15% of teams require:

• CMS Portal (complex enterprise workflows and deep system integration)

5% of teams need:

• Headless Portal (custom UX, modern frameworks, integration with existing sites)

Don’t over-engineer. Start simple, change later if needed.

↑ Back to top

Migration Paths: Start Simple, Grow as Needed

You can start simple and migrate up as your needs evolve:

Consumer Catalog → Developer Portal → Headless Portal or CMS Portal

Real-World Example: A fintech startup started with Consumer Catalog for internal APIs. Six months later, they launched a partner program and migrated to Developer Portal. A year after that, they needed to integrate the portal into their React-based website and moved to Headless Portal. They never needed CMS Portal.

Migration Tips:

• Start with the simplest option that meets your needs
• Document everything from day one
• Plan for growth, but don’t over-engineer
• Headless and CMS are different paths—choose based on your team’s strengths

↑ Back to top

Best Practices: Lessons from the Field

For Consumer Catalog Users:

• Perfect for internal APIs—don’t overthink it
• Document your APIs well (it’s all you’ve got)
• Plan migration path if you might go external

For Developer Portal Users:

• Max out configuration before considering other options
• Use custom CSS effectively—it goes a long way
• Create reusable content types
• Document your customizations
• This meets 80% of external portal needs

For CMS Portal Users:

• Establish update procedures on day one
• Implement automated security scanning
• Follow Drupal coding standards religiously
• Maintain dev/test/prod environments
• Budget for ongoing maintenance
• Only choose this if you truly need Drupal-specific features

For Headless Portal Users:

• Choose modern, maintainable frontend frameworks
• Version control everything
• Document your API integration patterns
• Plan for API Connect Portal API changes
• Maintain dev/test/prod environments
• Budget for ongoing maintenance
• Build reusable components from the start

↑ Back to top

The Bottom Line

Most teams should start here:

• Internal APIs? Consumer Catalog (it’s free and instant)
• External APIs? Developer Portal (it’s powerful and IBM-managed)

Consider these specialized options when:

• You need complete UX control with modern frameworks → Headless Portal
• You need complex Drupal-based enterprise workflows → CMS Portal

Don’t make this mistake: My biggest concern, is Teams jumping to CMS Portal because “we might need it someday.” Start simple. Developer Portal handles 80% of use cases. You can always migrate up.

My recommendation:

• 80% of teams: Consumer Catalog or Developer Portal
• 15% of teams: CMS Portal (complex Drupal-based enterprise requirements)
• 5% of teams: Headless Portal (modern UX, existing site integration)

Headless vs CMS: Which to choose?

• Choose CMS if you have Drupal developers and need Drupal-specific features
• Choose Headless if you have strong frontend developers and want modern frameworks

Choose based on what you need today and your team’s strengths, not what you might need in three years. Your future self will thank you.

↑ Back to top

Resources

• IBM Documentation: Consumer Catalog vs Developer Portal
• IBM Documentation: Customizing Developer Portal
• IBM Documentation: Using CMS Portal