Documentation

Getting Started

APIndex is an open-source API catalog and management platform that helps teams discover, organize, test, and visualize their APIs in one place. It provides:

• Centralized API Catalog — Register, tag, and organize all your APIs
• Network Map — Interactive visualization of API dependencies
• Environment Management — Manage dev, staging, and production environments with variables
• Built-in API Tester — Test API endpoints directly from the UI
• Role-Based Access Control — Fine-grained permissions with custom roles
• Multi-Organization Support — Create and switch between organizations
• LDAP/AD Integration — Enterprise authentication (Business plan)
• Audit Logging — Track all changes (Business plan)

Prerequisites

• Docker — version 20.10 or later
• Docker Compose — version 2.0 or later
• Git — for cloning the repository

Installation

Get APIndex running locally in three steps:

1. Clone the repository

git clone https://github.com/apindex/apindex.git
cd apindex

2. Configure environment

cp .env.example .env
# Edit .env with your settings (see Configuration section)

3. Start the services

# Development mode
docker compose up -d

# Production mode
docker compose -f docker/docker-compose.prod.yml up -d

Verify installation

# Check container status
docker compose ps

# API health check
curl http://localhost:8000/health

# Access the UI
# Development: http://localhost:5173
# Production: http://localhost:8080

Default Credentials

On first startup, APIndex creates a superuser account. Default credentials (change these!):

• Email: admin@apindex.local
• Password: changeme

Configuration

APIndex is configured via environment variables. Copy .env.example and adjust the values.

Database

Security

License & Instance

Architecture

APIndex consists of three main services:

Default Ports

API Catalog

The API Catalog is the central registry for all your APIs. Organize them with collections, tags, and detailed metadata.

Creating an API

Click Add API and provide:

• Name — Display name for the API
• Slug — URL-friendly identifier (auto-generated)
• Description — What the API does
• Type — REST, GraphQL, gRPC, SOAP, or WebSocket
• Base URL — The API's base endpoint
• Tags — For filtering and organization
• Collection — Group related APIs together

Importing APIs

APIndex supports importing OpenAPI 3.x, Swagger 2.0, and WSDL specifications:

• Upload a file (JSON, YAML, or XML)
• Paste spec content directly
• Import from URL

Endpoints, schemas, and authentication requirements are automatically parsed.

API Versions

Each API can have multiple versions. Mark versions as published or deprecated. Only one version can be the "current" version displayed by default.

Upstream Connections

Define which other APIs or external services this API depends on. These connections are visualized in the Network Map.

Network Map

The Network Map provides an interactive force-directed graph visualization showing how your APIs connect to each other and external services.

Features

• Interactive Graph — Drag nodes, zoom, and pan
• Dependency Lines — Arrows show data flow direction
• Click to Navigate — Click any API node to view details
• Connection Types — Visual distinction for internal vs external

Adding Connections

Edit any API and add upstream URLs in the "Connections" section. For each connection, specify:

• Name — Display name for the connection
• URL — Target endpoint (matched to other APIs if internal)
• Type — Internal API or External service
• Direction — Upstream (this API calls it) or Downstream (it calls this API)

Environments

Environments let you manage different configurations for development, staging, and production.

Environment Variables

Each environment can store key-value pairs that are substituted in API requests:

• Regular Variables — Visible to all users with access
• Secret Variables — Hidden after creation, only values are used

Use variables in API Tester with {{ variable_name }} syntax.

Testing Control

Enable or disable the "Allow Testing" flag per environment to control which environments can be used in the API Tester.

Limits

Community: 1 environment • Team/Business: Unlimited

API Testing

The built-in API Tester lets you make HTTP requests directly from the UI without external tools.

Features

• All HTTP Methods — GET, POST, PUT, PATCH, DELETE, etc.
• Custom Headers — Add any headers including Authorization
• Request Body — JSON, form data, or raw text
• Environment Variables — Select environment and use variables
• Response Viewer — Formatted JSON, headers, status, timing
• SSL Verification — Toggle SSL certificate verification

Request History

All requests are saved to history. View your recent requests or browse organization-wide history (with permission).

User Management

APIndex includes role-based access control (RBAC) with predefined and custom roles.

Default Roles

Custom Roles (Team+)

Create custom roles with specific permission combinations for your organization's needs.

User Limits

Community: 3 users • Team: 25 users • Business: Unlimited

Organizations

Users can belong to multiple organizations and switch between them. Each organization has its own:

• API catalog and collections
• Environments and variables
• Users and roles
• License and billing
• Audit log (Business plan)

Creating Organizations

Click the organization switcher in the sidebar and select "Create Organization". You become the owner of any organization you create.

Switching Organizations

Use the organization switcher to move between organizations. Your permissions may differ per organization based on your assigned roles.

LDAP / Active Directory

Business Plan — APIndex supports LDAP and Active Directory for enterprise authentication.

Configuration

Navigate to LDAP Settings in the sidebar and configure:

• Server URL — e.g., ldaps://ldap.example.com:636
• Bind DN — Service account DN for searches
• Bind Password — Service account password
• User Search Base — e.g., ou=People,dc=example,dc=com
• User Search Filter — e.g., (uid={username})

Group-to-Role Mapping

Map LDAP groups to APIndex roles. Users are automatically assigned roles based on their group membership.

Audit Log

Business Plan — Track all changes made in your organization.

Tracked Events

• API created, updated, deleted
• User created, updated, deleted
• Role created, updated, deleted
• Environment changes
• Collection changes
• API imports

Log Details

Each log entry includes:

• Timestamp
• User who performed the action (name and email preserved even if user is deleted)
• Action type (create, update, delete)
• Entity type and ID
• Changes made (before/after for updates)

Docker Deployment

The recommended way to deploy APIndex in production using Docker Compose.

docker-compose.prod.yml

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: apindex-db
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-apindex}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB:-apindex}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-apindex} -d ${POSTGRES_DB:-apindex}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  backend:
    image: apindex/backend:${APINDEX_VERSION:-latest}
    container_name: apindex-backend
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_USER=${POSTGRES_USER:-apindex}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB:-apindex}
      - SECRET_KEY=${SECRET_KEY:?Set SECRET_KEY}
      - DEBUG=false
      - LICENSE_SERVER_URL=${LICENSE_SERVER_URL:-}
      - INSTANCE_NAME=${INSTANCE_NAME:-default}
      - FIRST_SUPERUSER_EMAIL=${FIRST_SUPERUSER_EMAIL:-admin@apindex.local}
      - FIRST_SUPERUSER_PASSWORD=${FIRST_SUPERUSER_PASSWORD:-changeme}
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  frontend:
    image: apindex/frontend:${APINDEX_VERSION:-latest}
    container_name: apindex-frontend
    environment:
      - BACKEND_URL=http://backend:8000
    ports:
      - "${PORT:-8080}:80"
    depends_on:
      - backend
    restart: unless-stopped

volumes:
  postgres_data:

Deployment Steps

# 1. Create .env file
cat > .env << 'EOF'
POSTGRES_PASSWORD=your-secure-password
SECRET_KEY=$(openssl rand -hex 32)
FIRST_SUPERUSER_EMAIL=admin@yourcompany.com
FIRST_SUPERUSER_PASSWORD=change-this-password
PORT=8080
EOF

# 2. Start services
docker compose -f docker-compose.prod.yml up -d

# 3. Check status
docker compose -f docker-compose.prod.yml ps

# 4. View logs
docker compose -f docker-compose.prod.yml logs -f

Reverse Proxy (nginx)

server {
    listen 443 ssl http2;
    server_name apindex.yourcompany.com;

    ssl_certificate /etc/ssl/certs/apindex.crt;
    ssl_certificate_key /etc/ssl/private/apindex.key;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Kubernetes Deployment

Deploy APIndex on Kubernetes using the manifest below. Includes ConfigMap, Secret, Deployments, Services, and Ingress.

Quick Start

# 1. Download the manifest
curl -O https://docs.apindex.dev/k8s/apindex.yaml

# 2. Edit the ConfigMap and Secret values
# IMPORTANT: Change all default passwords and secrets!

# 3. Apply the manifest
kubectl apply -f apindex.yaml

# 4. Check deployment status
kubectl -n apindex get pods

# 5. Get the ingress IP/hostname
kubectl -n apindex get ingress

Full Manifest (apindex.yaml)

# APIndex Kubernetes Deployment
# Apply with: kubectl apply -f apindex.yaml

---
# Namespace
apiVersion: v1
kind: Namespace
metadata:
  name: apindex
  labels:
    app.kubernetes.io/name: apindex

---
# ConfigMap - Non-sensitive configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: apindex-config
  namespace: apindex
data:
  POSTGRES_HOST: "postgres"
  POSTGRES_PORT: "5432"
  POSTGRES_DB: "apindex"
  POSTGRES_USER: "apindex"
  DEBUG: "false"
  INSTANCE_NAME: "default"
  BACKEND_URL: "http://backend:8000"
  LICENSE_SERVER_URL: ""

---
# Secret - CHANGE THESE VALUES!
# Generate base64: echo -n 'your-value' | base64
apiVersion: v1
kind: Secret
metadata:
  name: apindex-secrets
  namespace: apindex
type: Opaque
data:
  POSTGRES_PASSWORD: Y2hhbmdlbWU=  # changeme
  SECRET_KEY: Y2hhbmdlLXRoaXMtdG8tYS1zZWN1cmUtcmFuZG9tLXN0cmluZw==
  FIRST_SUPERUSER_EMAIL: YWRtaW5AYXBpbmRleC5sb2NhbA==
  FIRST_SUPERUSER_PASSWORD: Y2hhbmdlbWU=

---
# PostgreSQL PVC
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
  namespace: apindex
spec:
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 10Gi

---
# PostgreSQL Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  namespace: apindex
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/component: database
  template:
    metadata:
      labels:
        app.kubernetes.io/component: database
    spec:
      containers:
        - name: postgres
          image: postgres:16-alpine
          ports: [{containerPort: 5432}]
          env:
            - name: POSTGRES_USER
              valueFrom: {configMapKeyRef: {name: apindex-config, key: POSTGRES_USER}}
            - name: POSTGRES_DB
              valueFrom: {configMapKeyRef: {name: apindex-config, key: POSTGRES_DB}}
            - name: POSTGRES_PASSWORD
              valueFrom: {secretKeyRef: {name: apindex-secrets, key: POSTGRES_PASSWORD}}
          volumeMounts:
            - name: postgres-data
              mountPath: /var/lib/postgresql/data
          resources:
            requests: {memory: "256Mi", cpu: "100m"}
            limits: {memory: "1Gi", cpu: "500m"}
      volumes:
        - name: postgres-data
          persistentVolumeClaim: {claimName: postgres-pvc}

---
# PostgreSQL Service
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: apindex
spec:
  ports: [{port: 5432}]
  selector:
    app.kubernetes.io/component: database

---
# Backend Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  namespace: apindex
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/component: backend
  template:
    metadata:
      labels:
        app.kubernetes.io/component: backend
    spec:
      containers:
        - name: backend
          image: apindex/backend:latest
          ports: [{containerPort: 8000}]
          env:
            - name: POSTGRES_HOST
              valueFrom: {configMapKeyRef: {name: apindex-config, key: POSTGRES_HOST}}
            - name: POSTGRES_PORT
              valueFrom: {configMapKeyRef: {name: apindex-config, key: POSTGRES_PORT}}
            - name: POSTGRES_USER
              valueFrom: {configMapKeyRef: {name: apindex-config, key: POSTGRES_USER}}
            - name: POSTGRES_DB
              valueFrom: {configMapKeyRef: {name: apindex-config, key: POSTGRES_DB}}
            - name: POSTGRES_PASSWORD
              valueFrom: {secretKeyRef: {name: apindex-secrets, key: POSTGRES_PASSWORD}}
            - name: SECRET_KEY
              valueFrom: {secretKeyRef: {name: apindex-secrets, key: SECRET_KEY}}
            - name: DEBUG
              valueFrom: {configMapKeyRef: {name: apindex-config, key: DEBUG}}
            - name: INSTANCE_NAME
              valueFrom: {configMapKeyRef: {name: apindex-config, key: INSTANCE_NAME}}
            - name: LICENSE_SERVER_URL
              valueFrom: {configMapKeyRef: {name: apindex-config, key: LICENSE_SERVER_URL}}
            - name: FIRST_SUPERUSER_EMAIL
              valueFrom: {secretKeyRef: {name: apindex-secrets, key: FIRST_SUPERUSER_EMAIL}}
            - name: FIRST_SUPERUSER_PASSWORD
              valueFrom: {secretKeyRef: {name: apindex-secrets, key: FIRST_SUPERUSER_PASSWORD}}
          livenessProbe:
            httpGet: {path: /health, port: 8000}
            initialDelaySeconds: 30
          readinessProbe:
            httpGet: {path: /health, port: 8000}
            initialDelaySeconds: 10
          resources:
            requests: {memory: "256Mi", cpu: "100m"}
            limits: {memory: "1Gi", cpu: "1000m"}

---
# Backend Service
apiVersion: v1
kind: Service
metadata:
  name: backend
  namespace: apindex
spec:
  ports: [{port: 8000}]
  selector:
    app.kubernetes.io/component: backend

---
# Frontend Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  namespace: apindex
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/component: frontend
  template:
    metadata:
      labels:
        app.kubernetes.io/component: frontend
    spec:
      containers:
        - name: frontend
          image: apindex/frontend:latest
          ports: [{containerPort: 80}]
          env:
            - name: BACKEND_URL
              valueFrom: {configMapKeyRef: {name: apindex-config, key: BACKEND_URL}}
          resources:
            requests: {memory: "64Mi", cpu: "50m"}
            limits: {memory: "256Mi", cpu: "200m"}

---
# Frontend Service
apiVersion: v1
kind: Service
metadata:
  name: frontend
  namespace: apindex
spec:
  ports: [{port: 80}]
  selector:
    app.kubernetes.io/component: frontend

---
# Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: apindex-ingress
  namespace: apindex
spec:
  rules:
    - host: apindex.example.com  # Change this!
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend
                port: {number: 80}

Customization

• Change apindex.example.com to your domain in the Ingress
• Update Secret values (generate new base64 values)
• Adjust resource limits based on your cluster capacity
• Add TLS configuration to Ingress for HTTPS
• Configure a StorageClass for the PVC if needed