OpenAPI Specification & Developer Tooling

Complete guide to working with the Olympus Cloud OpenAPI specification, generating client code, and using developer tools.

Overview

The Olympus Cloud platform provides a comprehensive OpenAPI 3.0 specification that documents all API endpoints, request/response schemas, and authentication requirements. This specification powers interactive documentation, SDK generation, and API testing tools.

Key Resources

Resource	URL	Description
API Reference	developers.olympuscloud.ai/docs	Interactive Swagger UI
OpenAPI Spec	api.olympuscloud.ai/openapi.json	Raw specification
Redoc	developers.olympuscloud.ai/redoc	Alternative documentation
Postman Collection	developers.olympuscloud.ai/postman	Import-ready collection
REST API Examples	REST API Examples	Language examples

---

OpenAPI Specification

Specification Location

The OpenAPI specification is available in multiple formats:

# JSON format
curl https://api.olympuscloud.ai/openapi.json

# YAML format
curl https://api.olympuscloud.ai/openapi.yaml

# Versioned specs
curl https://api.olympuscloud.ai/v1/openapi.json
curl https://api.olympuscloud.ai/v2/openapi.json

Specification Structure

openapi: 3.0.0
info:
  title: Olympus Cloud API
  version: 1.0.0
  description: Unified API for Olympus Cloud services

servers:
  - url: https://api.olympuscloud.ai/v1
    description: Production
  - url: https://sandbox-api.olympuscloud.ai/v1
    description: Sandbox

paths:
  /orders:
    get: ...
    post: ...
  /menu:
    get: ...
  # ... all endpoints

components:
  schemas:
    Order: ...
    MenuItem: ...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

API Categories

Category	Base Path	Description
Authentication	/auth/*	Login, tokens, OAuth
Orders	/orders/*	Order management
Menu	/menu/*	Menu items, categories
Payments	/payments/*	Payment processing
Inventory	/inventory/*	Stock management
Analytics	/analytics/*	Reports, dashboards
Platform	/platform/*	Tenants, locations
Automation	/automation/*	Rules, triggers
Developer	/developers/*	Portal APIs

---

Interactive Documentation

Swagger UI

Access the interactive API explorer at developers.olympuscloud.ai/docs.

Features:

• Try It Out - Execute API calls directly
• Authentication - Enter API keys or tokens
• Schema Explorer - View request/response structures
• Examples - Copy sample requests
• Code Generation - Generate client code snippets

Using Swagger UI

1. Navigate to developers.olympuscloud.ai/docs
2. Click Authorize button
3. Enter your API key: X-API-Key: your-api-key
4. Expand an endpoint category
5. Click Try it out
6. Fill in parameters
7. Click Execute
8. View the response

Redoc Documentation

Alternative documentation at developers.olympuscloud.ai/redoc with:

• Three-panel layout
• Deep linking to endpoints
• Search functionality
• PDF export
• Better schema visualization

---

Code Generation

Using OpenAPI Generator

Generate client SDKs using OpenAPI Generator:

# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i https://api.olympuscloud.ai/openapi.json \
  -g typescript-axios \
  -o ./generated/typescript

# Generate Python client
openapi-generator-cli generate \
  -i https://api.olympuscloud.ai/openapi.json \
  -g python \
  -o ./generated/python

# Generate Go client
openapi-generator-cli generate \
  -i https://api.olympuscloud.ai/openapi.json \
  -g go \
  -o ./generated/go

# Generate Rust client
openapi-generator-cli generate \
  -i https://api.olympuscloud.ai/openapi.json \
  -g rust \
  -o ./generated/rust

Available Generators

Language	Generator	Notes
TypeScript	typescript-axios	Axios-based client
TypeScript	typescript-fetch	Fetch-based client
Python	python	Requests-based client
Go	go	Native HTTP client
Rust	rust	Reqwest-based client
Java	java	OkHttp client
Swift	swift5	URLSession client
Kotlin	kotlin	OkHttp client

Generator Configuration

Create a config file for customization:

# openapi-generator-config.yaml
generateAliasAsModel: true
packageName: olympus
projectName: olympus-client
additionalProperties:
  apiPackage: api
  modelPackage: models
  supportsES6: true
  withInterfaces: true

openapi-generator-cli generate \
  -i https://api.olympuscloud.ai/openapi.json \
  -g typescript-axios \
  -o ./generated/typescript \
  -c openapi-generator-config.yaml

Using Generated Clients

TypeScript (using generated client):

import { OrdersApi, Configuration } from './generated/typescript';

const config = new Configuration({
  basePath: 'https://dev.api.olympuscloud.ai/v1',
  accessToken: 'your-jwt-token',  // From POST /v1/auth/login
});

const ordersApi = new OrdersApi(config);

// List orders
const orders = await ordersApi.listOrders({
  locationId: '550e8400-e29b-41d4-a716-446655449110',
  status: 'open',
});

// Create order
const newOrder = await ordersApi.createOrder({
  orderRequest: {
    locationId: '550e8400-e29b-41d4-a716-446655449110',
    items: [{ menuItemId: 'item-456', quantity: 2 }],
  },
});

Python (using requests):

import requests

BASE_URL = "https://dev.api.olympuscloud.ai/v1"
TOKEN = "your-jwt-token"  # From POST /v1/auth/login
headers = {"Authorization": f"Bearer {TOKEN}"}

# List orders
orders = requests.get(f"{BASE_URL}/commerce/orders", headers=headers).json()

# Create order
new_order = requests.post(f"{BASE_URL}/commerce/orders", headers=headers, json={
    "location_id": "550e8400-e29b-41d4-a716-446655449110",
    "source": "pos",
    "currency": "USD",
    "items": [{"menu_item_id": "item-456", "name": "Burger", "quantity": 2, "unit_price": 12.99}]
}).json()

Go:

package main

import (
    "context"
    "github.com/your-org/olympus-client-go"
)

func main() {
    cfg := olympus.NewConfiguration()
    cfg.AddDefaultHeader("X-API-Key", "your-api-key")

    client := olympus.NewAPIClient(cfg)

    // List orders
    orders, _, err := client.OrdersApi.ListOrders(context.Background()).
        LocationId("loc-123").
        Status("open").
        Execute()

    // Create order
    newOrder, _, err := client.OrdersApi.CreateOrder(context.Background()).
        OrderRequest(olympus.OrderRequest{
            LocationId: "loc-123",
            Items: []olympus.OrderItem{
                {MenuItemId: "item-456", Quantity: 2},
            },
        }).
        Execute()
}

---

API Testing Tools

Postman Collection

Import the Olympus Cloud Postman collection:

1. Open Postman
2. Click Import
3. Enter URL: https://developers.olympuscloud.ai/postman/collection.json
4. Import environment: https://developers.olympuscloud.ai/postman/environment.json
5. Set variables in environment

Postman Environment Variables

Variable	Description
base_url	https://api.olympuscloud.ai/v1
access_token	JWT access token (from POST /v1/auth/login)
tenant_id	Your tenant ID
location_id	Target location ID

Insomnia Import

Import into Insomnia:

curl -o olympus-insomnia.json \
  https://developers.olympuscloud.ai/insomnia/collection.json

# Import via Insomnia UI or CLI
insomnia import olympus-insomnia.json

HTTPie Examples

# List orders
http GET https://api.olympuscloud.ai/v1/orders \
  X-API-Key:your-api-key \
  location_id==loc-123 \
  status==open

# Create order
http POST https://api.olympuscloud.ai/v1/orders \
  X-API-Key:your-api-key \
  location_id=loc-123 \
  items:='[{"menu_item_id": "item-456", "quantity": 2}]'

cURL Examples

# List orders
curl -X GET "https://api.olympuscloud.ai/v1/orders?location_id=loc-123&status=open" \
  -H "X-API-Key: your-api-key"

# Create order
curl -X POST "https://api.olympuscloud.ai/v1/orders" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "loc-123",
    "items": [{"menu_item_id": "item-456", "quantity": 2}]
  }'

---

SDK Documentation

REST API Examples

Resource	Description
REST API Examples	Language-agnostic REST API examples (curl, Python, JS, Go)

REST API Quick Start

All API access uses standard REST with JWT Bearer authentication. No SDK is required.

TypeScript (fetch):

const API_BASE = 'https://dev.api.olympuscloud.ai/v1';

// Authenticate to get a JWT
const loginRes = await fetch(`${API_BASE}/auth/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com', password: 'password' }),
});
const { status } = await loginRes.json();
const accessToken = status.access_token;

// Use the JWT for subsequent requests
const ordersRes = await fetch(`${API_BASE}/commerce/orders?location_id=loc-123`, {
  headers: { 'Authorization': `Bearer ${accessToken}` },
});
const orders = await ordersRes.json();

Python (requests):

import requests

API_BASE = "https://dev.api.olympuscloud.ai/v1"

# Authenticate to get a JWT
login_res = requests.post(f"{API_BASE}/auth/login", json={
    "email": "user@example.com",
    "password": "password",
})
access_token = login_res.json()["status"]["access_token"]

# Use the JWT for subsequent requests
headers = {"Authorization": f"Bearer {access_token}"}
orders = requests.get(f"{API_BASE}/commerce/orders", params={"location_id": "loc-123"}, headers=headers).json()

---

Webhook Testing

Webhook.site Integration

Test webhooks using webhook.site:

1. Go to webhook.site
2. Copy your unique URL
3. Register webhook in Developer Portal
4. Trigger events in sandbox
5. View payloads in webhook.site

Local Webhook Testing

Use ngrok for local development:

# Start ngrok tunnel
ngrok http 3000

# Register webhook with ngrok URL
curl -X POST "https://api.olympuscloud.ai/v1/webhooks" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok.io/webhooks",
    "events": ["order.created", "order.updated"]
  }'

Webhook Signature Verification

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

---

API Versioning

Version Strategy

The API uses URL-based versioning:

Version	Base URL	Status
v1	api.olympuscloud.ai/v1	Current
v2	api.olympuscloud.ai/v2	Beta

Version Header

Alternatively, use the API-Version header:

GET /orders HTTP/1.1
Host: api.olympuscloud.ai
API-Version: 2024-01-15

Deprecation Policy

Timeline	Action
-6 months	New version announced
-3 months	Deprecation warning in docs
-1 month	Deprecation header in responses
End of life	Old version returns 410 Gone

Deprecation Headers

Sunset: Sat, 15 Jun 2025 00:00:00 GMT
Deprecation: true
Link: <https://api.olympuscloud.ai/v2>; rel="successor-version"

---

GraphQL API

GraphQL Endpoint

POST https://api.olympuscloud.ai/graphql

GraphQL Playground

Interactive GraphQL IDE at developers.olympuscloud.ai/graphql.

Example Query

query GetOrders($locationId: ID!, $status: OrderStatus) {
  orders(locationId: $locationId, status: $status) {
    edges {
      node {
        id
        status
        total
        items {
          menuItem {
            name
            price
          }
          quantity
        }
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Example Mutation

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    order {
      id
      status
      total
    }
    errors {
      field
      message
    }
  }
}

GraphQL Code Generation

Use GraphQL Code Generator:

npm install -D @graphql-codegen/cli @graphql-codegen/typescript

# codegen.yml
schema: https://api.olympuscloud.ai/graphql
documents: "src/**/*.graphql"
generates:
  src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo

---

Rate Limiting

Rate Limit Tiers

Tier	Requests/min	Requests/hour
Free	60	1,000
Pro	600	10,000
Partner	6,000	100,000

Rate Limit Headers

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 542
X-RateLimit-Reset: 1704067200
Retry-After: 45

Handling Rate Limits

async function fetchWithRateLimit<T>(url: string): Promise<T> {
  const response = await fetch(url, { headers });

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    await sleep(retryAfter * 1000);
    return fetchWithRateLimit<T>(url);
  }

  return response.json();
}

---

Best Practices

API Usage

1. Use SDKs - Prefer official SDKs over raw HTTP
2. Handle errors - Implement proper error handling
3. Respect rate limits - Implement backoff strategies
4. Use pagination - Iterate through large result sets
5. Cache responses - Cache where appropriate

Security

danger

Never embed API keys in client-side code, mobile apps, or public repositories. API keys exposed in client code can be extracted and used to make unauthorized requests on your behalf. Always use server-side proxy endpoints or environment variables.

1. Secure API keys - Never expose in client code
2. Use environment variables - Store secrets securely
3. Validate webhooks - Verify webhook signatures
4. Use HTTPS - Always use encrypted connections
5. Rotate keys - Regularly rotate API keys

Performance

1. Batch requests - Use bulk endpoints when available
2. Use GraphQL - Request only needed fields
3. Implement caching - Cache static data
4. Use compression - Enable gzip compression
5. Monitor usage - Track API usage metrics

---

Related Documentation

• Developer Portal Overview - Portal guide
• Webhooks Guide - Webhook setup
• REST API Examples - Language-agnostic REST API examples (curl, Python, JS, Go)
• Rate Limiting - Rate limit details
• Authentication - Auth methods