Getting started with Orbitra API

Orbitra API provides a FastAPI-based foundation for building robust, production-grade REST APIs within the Orbitra ecosystem. It offers seamless integration with Orbitra Lake for data access, built-in authentication/authorization support, and a standardized project structure for rapid API development.

Key Concepts

What is Orbitra API ?

Orbitra API is a pre-configured FastAPI template that allows you to quickly build and deploy REST endpoints integrated with Orbitra’s data platform and built-in examples. It abstracts away infrastructure concerns and provides:

Pre-configured authentication: Automatic token validation and credential management via Orbitra Commons;
Orbitra Lake integration: Direct access to your data lake through the Lake SDK;
Development and deployment ready: Serverless execution on Azure Functions, pre-configured OpenTelemetry/Azure Monitor telemetry, CI/CD pipeline integration, and local dev container setup.

REST API Fundamentals

A REST API exposes your application’s functionality through HTTP endpoints:

Endpoints: URLs that represent resources (e.g., /api/tables, /api/data)
HTTP Methods: GET (retrieve), POST (create), PUT (update), DELETE (remove)
Request/Response: Structured data exchange using JSON
Status Codes: HTTP codes indicate success (2xx), client errors (4xx), or server errors (5xx)

Getting Started with the Template

1) Set Up Your Development Environment

From your template project root:

Using Dev Container (Recommended)
Manual Setup

Open the project in VS Code, press ctrl+shift+P and select “Reopen in Container”. This automatically configures:

Python 3.11+ with all dependencies
FastAPI development server
Debugging support
All required tools and libraries

# Install dependencies
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On macOS/Linux
# or
.venv\Scripts\activate  # On Windows

2) Understand the Main Components

API Initialization (`main.py`)

The template includes a minimal api/main.py file:

from fastapi import FastAPI

app = FastAPI(
    title="Orbitra API",
    description="REST API for accessing Orbitra data",
    version="1.0.0"
)

@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "orbitra-api"}

-> This is your starting point. You’ll add endpoints and routers to this file.

3) Create Your First Endpoint

Add an endpoint directly to your api/main.py:

from fastapi import FastAPI, HTTPException
from orbitra.lake import get_lake_client  # For Orbitra Lake integration

app = FastAPI(
    title="Orbitra API",
    description="REST API for accessing Orbitra data",
    version="1.0.0"
)

@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "orbitra-api"}

@app.get("/api/tables/{namespace}")
async def list_tables(namespace: str):
    """
    List all tables in a specified namespace.
    Args:
      - `namespace`: The namespace containing the tables
    
    Returns:
      - List of table names in the namespace
    """
    try:
        client = get_lake_client()
        tables = client.list_tables(namespace=namespace)
        return {
            "namespace": namespace,
            "tables": tables,
            "count": len(tables)
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

4) Run Your API Locally

VS Code/Cursor UI
Terminal

Open the Run and Debug panel in VS Code
Select “Python: API” configuration
Press F5 to launch

# From your project root, run the app directly
python api/main.py

The template already includes if __name__ == "__main__": with uvicorn.run(...), so either option works.

5) Test Your Endpoints

Using curl
Using Python
Using Swagger UI

# List tables in a namespace
curl -X GET "http://localhost:8000/api/tables/playground"

# Get table metadata
curl -X GET "http://localhost:8000/api/tables/playground/my_table"

import requests

BASE_URL = "http://localhost:8000"
NAMESPACE = "playground"
TABLE_NAME = "my_table"

# List tables
response = requests.get(f"{BASE_URL}/api/tables/{NAMESPACE}")
print(response.json())

# Get table metadata
response = requests.get(f"{BASE_URL}/api/tables/{NAMESPACE}/{TABLE_NAME}")
print(response.json())

Open http://localhost:8000/docs
Find the endpoint you want to test
Click “Try it out”
Enter parameters and click “Execute”
View the response

Deployment

Serverless runtime and telemetry (pre-configured)

The API template is packaged and deployed as an Azure Function App with telemetry enabled by default:

.pipelines/function_app.py wraps your FastAPI app using func.AsgiFunctionApp(...) for serverless execution;
.pipelines/host.json sets telemetrymode to OpenTelemetry and keeps HTTP routes at root ("routePrefix": "");
configure_azure_monitor() is enabled to export traces/metrics/logs to Azure Monitor.

No extra telemetry bootstrap is required for the default template flow. When you’ve finished developing the main.py file, add the pipeline to your DevOps and hit the run pipeline button in your project. Everything else is already set up for you:

Run the pipeline in .pipelines/pipeline.yaml (builds functionapp.zip with api/, .pipelines/function_app.py, and .pipelines/host.json);
Monitor via your platform observability stack and function app logs.

Next Steps

Review the Orbitra Lake documentation for data access patterns.
Explore the Flows SDK if you need to orchestrate backend processes.
Check the Commons SDK to understand the authentication scenarios.

​Key Concepts

​What is Orbitra API ?

​REST API Fundamentals

​Getting Started with the Template

​1) Set Up Your Development Environment

​2) Understand the Main Components

​API Initialization (main.py)

​3) Create Your First Endpoint

​4) Run Your API Locally

​5) Test Your Endpoints

​Deployment

​Serverless runtime and telemetry (pre-configured)

​Next Steps