API Path Structure

Luma API routes usually follow this pattern:

/v{version}/{resource}/{action}

We apologize for inconsistencies as we're still transitioning older endpoints to this format.

Components

Version: The version number (e.g., /v1/, /v2/) represents the version of that specific API route, not the entire API. This allows us to update individual endpoints independently.
Resource: The entity being operated on (e.g., event/ticket-types, events, calendars, users)
Action: The operation being performed (e.g., list, get, create, update, delete)

Naming Convention

We're transitioning to a consistent RESTful naming pattern. The ticket-types endpoints exemplify our target convention:

Example: Ticket Types API

GET  /v1/event/ticket-types/list    # List all ticket types for an event
GET  /v1/event/ticket-types/get     # Get a single ticket type
POST /v1/event/ticket-types/create  # Create a new ticket type
POST /v1/event/ticket-types/update  # Update an existing ticket type
POST /v1/event/ticket-types/delete  # Delete a ticket type

HTTP Methods

GET: Used for read operations (list, get)
POST: Used for write operations (create, update, delete)

We use POST for all write operations to maintain consistency and support complex request bodies when needed.

Route Versioning

Per-Route Versioning

Unlike traditional API versioning where the entire API shares a version number, Luma uses per-route versioning. This means:

Each endpoint can have its own version number
A /v2/ route indicates that specific endpoint was updated, not the entire API
You might use /v1/events/list alongside /v2/events/create in the same application

Benefits

This approach provides several advantages:

Gradual Migration: Adopt new endpoint versions at your own pace
Isolated Changes: Breaking changes to one endpoint don't affect others
Backward Compatibility: Older versions remain available until deprecated
Independent Evolution: Each endpoint evolves based on its specific requirements

Example Scenario

// Your application might use different versions for different endpoints
const events = await fetch("/v1/events/list", options); // Still using v1
const newEvent = await fetch("/v2/events/create", eventData); // Using updated v2
const tickets = await fetch("/v1/event/ticket-types/list"); // Using v1