REST Channels

Group and configure REST API endpoints with shared base paths, authentication, and middleware in Spala.

REST Channels

REST channels let you group related API endpoints under a shared configuration. All endpoints within a channel inherit the channel's base path, authentication settings, middleware, and rate limits, reducing repetition and keeping your API organized.

Check availability first

Most current projects should create endpoints directly in the API section and manage auth on each endpoint. This page is for workspaces where advanced REST Channels are enabled.

Creating a REST Channel

Navigate to the Channels section in the left sidebar

Click New Channel and select REST

Enter a channel name (e.g., "API v1")

Set the base path (e.g., /api/v1)

Configure authentication, middleware, and rate limiting

Save the channel

Channel Settings

Base Path

The base path is prepended to every endpoint in the channel. If your channel has a base path of /api/v1 and an endpoint with the path /users, the full URL becomes /api/v1/users.

Channel: "API v1"
Base Path: /api/v1

Endpoints:
  GET  /users        → GET  /api/v1/users
  POST /users        → POST /api/v1/users
  GET  /users/:id    → GET  /api/v1/users/:id
  GET  /products     → GET  /api/v1/products

This makes API versioning straightforward: create a new v2 channel with the base path /api/v2, copy the endpoints you want to update, and modify them independently.

Authentication

Set the authentication method at the channel level, and all endpoints within the channel will require it:

- None — No authentication required. Use for public endpoints like health checks and landing page data.
- JWT — Requires a valid JSON Web Token in the Authorization header. The decoded token payload is available to the endpoint function as vars.auth.
- API Key — Requires a valid API key in the X-API-Key header or as a query parameter.

// With JWT authentication enabled on the channel:
// vars.auth.userId  → 42
// vars.auth.role    → "admin"
// vars.auth.email   → "[email protected]"

Individual endpoints can override the channel's authentication setting. For example, you can set a channel to require JWT but mark a specific health-check endpoint as requiring no authentication.

Middleware

Channel middleware functions run before every endpoint in the channel. Common uses include:

- Logging — Record request details for all API calls
- Input sanitization — Clean or validate request bodies
- Role checking — Verify the authenticated user has the required role
- Request transformation — Add headers or modify the request body

Middleware functions run in order. If a middleware function throws an error, the endpoint function does not execute and the error is returned to the client.

Rate Limiting

Set a rate limit to restrict how many requests a single client can make per minute. When the limit is exceeded, the server returns a 429 Too Many Requests response.

Rate limits are tracked per client IP address by default. With JWT authentication enabled, limits are tracked per authenticated user instead, providing more accurate throttling.

Rate limits apply per channel. If a client is rate-limited on one channel, they can still make requests to endpoints on other channels.

CORS Configuration

Configure which origins are allowed to make cross-origin requests to endpoints in this channel. By default, CORS is configured to allow requests from any origin (*). For production, restrict this to your frontend domain(s):

{
  "origins": ["https://myapp.com", "https://admin.myapp.com"],
  "methods": ["GET", "POST", "PUT", "DELETE"],
  "headers": ["Authorization", "Content-Type"]
}

Organizing Your API

A typical Spala project might use channels like this:

| Channel | Base Path | Auth | Purpose |
|---|---|---|---|
| Public | / | None | Health check, public content |
| Auth | /auth | None | Login, register, forgot password |
| API | /api/v1 | JWT | Protected application endpoints |
| Admin | /admin | JWT + Role | Admin-only management endpoints |
| Webhooks | /webhooks | API Key | Incoming webhooks from third parties |

This structure keeps your API clean, secure, and easy to navigate as it grows.

A descriptive name for the channel
URL prefix applied to all endpoints (e.g., /api/v1)
Required auth method: None, JWT, or API Key
Maximum requests per minute per client (0 = unlimited)
Allowed origins for cross-origin requests
Middleware functions that run before each endpoint
Realtime Channels
/channels/realtime
WebSocket connections for live data updates
Channels Overview
/channels
Learn about all channel types in Spala
API Endpoints
/endpoints
Create the endpoints that channels group together