API Development
Caspian is built on top of FastAPI. Whether you need a dedicated backend service or hybrid API routes within your fullstack app, you have native access to high-performance async endpoints.
caspian.config.json has
"backendOnly": false. In this full-stack
project, /docs belongs to the Caspian
documentation UI and FastAPI's Swagger, ReDoc, and OpenAPI routes are not
registered by main.py. Those automatic API
docs are enabled when backend-only mode is true.
Backend-Only Mode
Best for when you want a standalone API service without the templating engine. This enables standard FastAPI features like automatic Swagger UI documentation by default.
Swagger UI
Automatic interactive docs available at /docs.
Lightweight
Disables the HTML rendering engine for maximum raw throughput.
Fullstack Hybrid Routes
In a fullstack application, you can mix UI pages and API endpoints.
Simply return a JSONResponse
from your page function to bypass the HTML renderer.
from fastapi import Request from fastapi.responses import JSONResponse # This function runs when you visit /api/users def page(request: Request): # Perform your logic (DB queries, etc.) users = [ "id": 1, "name": "Jefferson", "id": 2, "name": "Alice" ] # Return JSONResponse to bypass Caspian's HTML renderer return JSONResponse(content="data": users)
page() function.
If it sees a FastAPI Response object (like JSONResponse), it skips the Jinja2 template engine entirely,
giving you raw API performance.
Choosing HTTP Methods
Every route Caspian registers accepts
GET
and
POST
by default. To narrow or widen that, export a module-level
route_methods
list from the route's index.py. Caspian reads
it at registration time, uppercases and de-duplicates the entries, and
passes them straight to
app.add_api_route(...). Anything else gets
the usual FastAPI 405 Method Not Allowed.
from fastapi import Request from fastapi.responses import JSONResponse # Only accept POST on this endpoint route_methods = ["POST"] async def page(request: Request): payload = await request.json() return JSONResponse(content="received": True)
route_methods is read from
index.py only, so an HTML-only route always
keeps the GET/POST
default. Empty or non-list values are ignored rather than treated as
“no methods”.