public-api-server.md

Public API Server Component

Overview

The Public API Server is a component in Gitpod that provides a versioned, stable, and managed API for programmatic access to Gitpod functionality. It serves as the gateway for external integrations, automation, and third-party tools to interact with Gitpod's core services. The API is designed to be backward compatible, well-documented, and follows modern API design principles.

Purpose

The primary purposes of the Public API Server component are:

• Provide a stable, versioned API for programmatic access to Gitpod

• Enable third-party integrations and community-built tools

• Offer a consistent interface for automation and orchestration

• Support authentication and authorization for API access

• Serve as the canonical way to access Gitpod functionality programmatically

• Enable richer integrations with IDEs and development platforms

• Provide OpenID Connect (OIDC) authentication capabilities

• Support identity provider functionality

Architecture

The Public API Server is built as a Go service with several key components:

1. gRPC API: Core API implementation using gRPC and Connect

2. Authentication: Handles API tokens, session verification, and OIDC flows

3. Proxy Layer: Routes requests to internal Gitpod services

4. Metrics & Logging: Collects and exposes metrics and logs

5. Validation: Ensures request data meets API requirements

6. Webhooks: Handles external service webhooks (e.g., Stripe)

The component is designed to be the primary entry point for all programmatic interactions with Gitpod, abstracting away internal implementation details and providing a stable interface.

Key Files and Structure

• main.go: Entry point for the application

• cmd/root.go: Command-line interface setup

• cmd/run.go: Main server run command

• pkg/server/server.go: Core server implementation

• pkg/apiv1/: API service implementations

• pkg/auth/: Authentication and authorization

• pkg/oidc/: OpenID Connect implementation

• pkg/identityprovider/: Identity provider functionality

• pkg/proxy/: Request proxying to internal services

• pkg/webhooks/: Webhook handlers

API Services

The Public API Server provides several services:

1. Workspaces Service: Manage workspaces (create, start, stop, delete)

2. Teams Service: Manage teams and team membership

3. User Service: User information and management

4. SCM Service: Source code management integrations

5. Editor Service: IDE and editor configuration

6. IDE Client Service: IDE client interactions

7. Projects Service: Project management

8. OIDC Service: OpenID Connect authentication

9. Identity Provider Service: Identity provider functionality

10. Tokens Service: Personal access token management

Authentication

The component supports multiple authentication methods:

1. Personal Access Tokens: Long-lived tokens for API access

2. Session Authentication: Browser session-based authentication

3. OIDC Authentication: OpenID Connect flows for third-party authentication

4. Webhook Signatures: Verification of webhook payloads

Authentication is implemented using JSON Web Signatures (JWS) with both RSA-256 and HMAC-SHA256 algorithms.

Configuration

The Public API Server is configured through a JSON configuration file:

{
  "server": {
    "port": 3000,
    "address": "0.0.0.0"
  },
  "gitpodServiceURL": "https://gitpod.io/api",
  "publicURL": "https://api.gitpod.io",
  "sessionServiceAddress": "session-service:3000",
  "databaseConfigPath": "/etc/gitpod/db",
  "redis": {
    "address": "redis:6379"
  },
  "auth": {
    "pki": {
      "privateKeyPath": "/etc/gitpod/auth/private-key.pem",
      "publicKeyPath": "/etc/gitpod/auth/public-key.pem"
    },
    "session": {
      "cookieName": "gp:session",
      "maxAgeMs": 259200000
    }
  },
  "personalAccessTokenSigningKeyPath": "/etc/gitpod/auth/pat-key",
  "stripeWebhookSigningSecretPath": "/etc/gitpod/stripe/webhook-secret",
  "billingServiceAddress": "billing-service:3000"
}

Dependencies

Internal Dependencies

• components/common-go: Common Go utilities

• components/public-api: API definitions

• components/usage-api: Usage API definitions

• components/gitpod-protocol: Gitpod protocol definitions

• components/gitpod-db: Database access

External Dependencies

• gRPC and Connect for API implementation

• Redis for caching and session management

• GORM for database access

• Chi router for HTTP routing

• Prometheus for metrics

Integration Points

The Public API Server integrates with:

1. Gitpod Server: For core Gitpod functionality. The Public API Server often acts as a gRPC gateway, proxying requests to the Gitpod Server (TypeScript component) where the business logic for many gitpod.v1 services (like OrganizationService) is implemented.

2. Database: For persistent storage

3. Redis: For caching and session management

4. Billing Service: For billing-related operations

5. Session Service: For session management

6. External Identity Providers: For authentication

Security Considerations

The component implements several security measures:

1. Token Signing: Secure signing of personal access tokens

2. Session Verification: Validation of user sessions

3. Webhook Signature Verification: Ensures webhook payloads are authentic

4. CORS Protection: Controls cross-origin requests

5. Encryption: Database encryption for sensitive data

6. Logging: Comprehensive logging for security auditing

Metrics

The component exposes various metrics:

• Request counts and latencies

• Error rates

• Authentication failures

• Proxy performance

• OIDC flow completions

Common Usage Patterns

The Public API Server is typically used to:

1. Create and manage workspaces programmatically

2. Integrate Gitpod with CI/CD pipelines

3. Build custom dashboards and management tools

4. Automate workspace provisioning

5. Implement custom authentication flows

6. Integrate with third-party services

Related Components

• Server: Provides the core functionality that the Public API exposes

• Database: Stores user, workspace, and other data

• Proxy: Routes incoming traffic to appropriate services

• Billing Service: Handles billing-related operations

• Session Service: Manages user sessions