Skip to content
1337skills 1337skills

Gravitee Cheat Sheet

Overview

Gravitee is an open-source API management platform that provides a full lifecycle API management solution including an API gateway, management console, developer portal, and analytics dashboard. It supports REST, GraphQL, gRPC, WebSocket, and event-driven APIs with a policy-based architecture for request/response transformation.

Gravitee offers flexible deployment options including Docker, Kubernetes, and traditional installations. Key features include API design and documentation, subscription-based access management, fine-grained policies for security and traffic control, real-time analytics, and a customizable developer portal for API consumers.

Installation

Docker Compose

# Clone Gravitee Docker setup
curl -L https://bit.ly/gravitee-docker -o docker-compose.yml

# Or use the official repo
git clone https://github.com/gravitee-io/gravitee-api-management.git
cd gravitee-api-management/docker

docker compose up -d

# Components:
# Gateway: localhost:8082
# Management API: localhost:8083
# Console UI: localhost:8084
# Portal UI: localhost:8085
# MongoDB: localhost:27017
# Elasticsearch: localhost:9200

Helm Chart (Kubernetes)

helm repo add graviteeio https://helm.gravitee.io
helm repo update

helm install gravitee graviteeio/apim \
  --namespace gravitee --create-namespace \
  --set api.ingress.enabled=true \
  --set gateway.ingress.enabled=true \
  --set portal.ingress.enabled=true \
  --set ui.ingress.enabled=true

Default Credentials

# Management Console: http://localhost:8084
# Username: admin
# Password: admin

# Management API
# Base URL: http://localhost:8083/management
# Auth: Basic admin:admin

Management API

API Lifecycle

# List all APIs
curl -u admin:admin http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis

# Create an API
curl -X POST -u admin:admin \
  -H "Content-Type: application/json" \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis \
  -d '{
    "name": "My API",
    "version": "1.0",
    "description": "My first API",
    "contextPath": "/my-api",
    "endpoint": "http://backend:3000",
    "paths": {
      "/": []
    }
  }'

# Get API details
curl -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}

# Update an API
curl -X PUT -u admin:admin \
  -H "Content-Type: application/json" \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id} \
  -d @api-update.json

# Deploy API to gateway
curl -X POST -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}/deploy

# Start API
curl -X POST -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}?action=START

# Stop API
curl -X POST -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}?action=STOP

Plans and Subscriptions

# Create a plan (API Key)
curl -X POST -u admin:admin \
  -H "Content-Type: application/json" \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}/plans \
  -d '{
    "name": "Free Plan",
    "description": "Basic access with rate limiting",
    "security": "API_KEY",
    "validation": "AUTO",
    "status": "PUBLISHED",
    "paths": {
      "/": [
        {
          "rate-limit": {
            "rate": {
              "limit": 100,
              "periodTime": 1,
              "periodTimeUnit": "HOURS"
            }
          }
        }
      ]
    }
  }'

# List plans
curl -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}/plans

# Publish a plan
curl -X POST -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}/plans/{plan-id}/_publish

# List subscriptions
curl -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}/subscriptions

Policies

Common Policies

PolicyDescription
Rate LimitLimit request rate per time window
QuotaLimit total requests over a period
API KeyAuthenticate via API key header
JWTValidate JSON Web Tokens
OAuth2OAuth2 token introspection
IP FilteringWhitelist/blacklist IPs
Transform HeadersAdd/remove/modify headers
Transform BodyModify request/response body
CacheResponse caching
CORSCross-origin resource sharing
MockReturn mock responses
Assign ContentSet response content
LatencyAdd artificial latency (testing)
Circuit BreakerPrevent cascading failures

Policy Configuration (JSON)

{
  "paths": {
    "/": [
      {
        "methods": ["GET", "POST"],
        "rate-limit": {
          "rate": {
            "limit": 50,
            "periodTime": 1,
            "periodTimeUnit": "MINUTES"
          }
        },
        "transform-headers": {
          "addHeaders": [
            { "name": "X-Gateway", "value": "Gravitee" }
          ],
          "removeHeaders": ["Server"]
        },
        "jwt": {
          "signature": "RSA_RS256",
          "publicKeyResolver": "JWKS_URL",
          "jwksUrl": "https://auth.example.com/.well-known/jwks.json",
          "extractClaims": true
        }
      }
    ]
  }
}

Configuration

Gateway Configuration (gravitee.yml)

http:
  port: 8082
  host: 0.0.0.0
  requestTimeout: 30000
  idleTimeout: 60000

management:
  type: http
  http:
    url: http://localhost:8083/management/
    authentication:
      basic:
        username: admin
        password: admin

ratelimit:
  type: mongodb
  mongodb:
    uri: mongodb://localhost:27017/gravitee

reporters:
  elasticsearch:
    enabled: true
    endpoints:
      - http://localhost:9200
    index: gravitee
    bulk:
      actions: 1000
      flush_interval: 5

Logging Configuration

logging:
  mode: CLIENT_PROXY
  content: HEADERS_PAYLOADS
  scope: REQUEST_RESPONSE
  condition: "{#request.headers['X-Debug'] == 'true'}"
  maxSizeLogMessage: 10000

Advanced Usage

API Import (OpenAPI/Swagger)

# Import from Swagger/OpenAPI spec
curl -X POST -u admin:admin \
  -H "Content-Type: application/json" \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/import/swagger \
  -d '{
    "type": "URL",
    "payload": "https://petstore.swagger.io/v2/swagger.json",
    "with_documentation": true,
    "with_path_mapping": true,
    "with_policies": ["mock"]
  }'

Health Check Configuration

{
  "healthcheck": {
    "enabled": true,
    "schedule": "*/30 * * * * *",
    "steps": [
      {
        "request": {
          "path": "/health",
          "method": "GET",
          "headers": []
        },
        "response": {
          "assertions": ["#response.status == 200"]
        }
      }
    ]
  }
}

API Quality Metrics

# Get API analytics
curl -u admin:admin \
  "http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}/analytics?type=group_by&field=status&interval=86400000&from=1716000000000&to=1716100000000"

# Get API health
curl -u admin:admin \
  http://localhost:8083/management/organizations/DEFAULT/environments/DEFAULT/apis/{api-id}/health

Developer Portal

# List published APIs on portal
curl http://localhost:8083/portal/environments/DEFAULT/apis

# Get API documentation
curl http://localhost:8083/portal/environments/DEFAULT/apis/{api-id}/pages

# Create application (as developer)
curl -X POST -u developer:developer \
  -H "Content-Type: application/json" \
  http://localhost:8083/portal/environments/DEFAULT/applications \
  -d '{
    "name": "My App",
    "description": "My consumer application",
    "type": "WEB"
  }'

# Subscribe to a plan
curl -X POST -u developer:developer \
  -H "Content-Type: application/json" \
  http://localhost:8083/portal/environments/DEFAULT/applications/{app-id}/subscriptions \
  -d '{
    "plan": "{plan-id}"
  }'

Troubleshooting

IssueSolution
API returns 404Deploy the API to gateway; verify context path is correct
Gateway not startingCheck MongoDB and Elasticsearch connectivity
Policies not appliedRe-deploy the API after policy changes
Subscription pendingApprove subscription in management console if validation is manual
Analytics missingVerify Elasticsearch is healthy; check reporter configuration
CORS errorsAdd CORS policy to the API; configure allowed origins
JWT validation failsCheck JWKS URL is reachable; verify algorithm matches
High latencyReview policy chain order; check backend response times