Developer Portal Engineering

A developer portal is the front door to your platform. When a new engineer joins, they need to find services, understand APIs, provision infrastructure, and deploy code. Without a portal, this knowledge is scattered across wikis, Slack threads, and tribal knowledge. An internal developer portal consolidates everything into a single, searchable, self-serve experience.

Developer Portal Components

Core Components:

1. Service Catalog:
   ├── All services with ownership, status, dependencies
   ├── Health status (green/yellow/red)
   ├── Documentation links
   ├── Repository links
   └── On-call contacts

2. API Documentation:
   ├── OpenAPI/Swagger specs
   ├── GraphQL schema explorer
   ├── Interactive API playground (try it live)
   └── Authentication guide

3. Golden Paths (Templates):
   ├── "Create a new REST API" → Scaffolded project
   ├── "Create a new React app" → Scaffolded with CI/CD
   ├── "Create a new data pipeline" → Scaffolded with monitoring
   └── Each template includes: repo, CI/CD, monitoring, alerts

4. Infrastructure Self-Service:
   ├── "I need a database" → Provisioned in 5 minutes
   ├── "I need a Kafka topic" → Created with schema
   ├── "I need a DNS entry" → Requested and auto-approved
   └── All via UI forms or CLI commands

5. Documentation Hub:
   ├── Architecture Decision Records (ADRs)
   ├── RFCs and design docs
   ├── Runbooks and playbooks
   └── Onboarding guides

Backstage Implementation

# catalog-info.yaml (Backstage service definition)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: Handles order creation, updates, and fulfillment
  annotations:
    github.com/project-slug: company/order-service
    pagerduty.com/service-id: P12345
    grafana/dashboard-selector: order-service
  tags:
    - java
    - spring-boot
    - tier-1
  links:
    - url: https://grafana.internal/d/orders
      title: Grafana Dashboard
    - url: https://wiki.internal/order-service
      title: Wiki

spec:
  type: service
  owner: team-commerce
  lifecycle: production
  
  system: order-processing
  
  providesApis:
    - orders-api
  consumesApis:
    - payments-api
    - inventory-api
  
  dependsOn:
    - resource:orders-database
    - resource:orders-cache

Anti-Patterns

The developer portal is the most impactful investment a platform team can make. It reduces onboarding time, eliminates repetitive questions, and creates a single source of truth for how to build and deploy software within your organization.