Skip to main content

๐Ÿš€ API Documentation

The Backstage Cinema Management System provides a comprehensive RESTful API for managing all aspects of cinema operations. This documentation covers endpoints, authentication, and integration guidelines.

๐Ÿ“‹ Quick Accessโ€‹

API Base URLsโ€‹

  • Development: http://localhost:3000
  • Production: https://api.backstagecinema.com (when deployed)

Interactive Documentationโ€‹

  • Swagger UI: http://localhost:3000/api/docs - Interactive API documentation with live testing
  • Health Check: http://localhost:3000/health - API health status
  • API Base: http://localhost:3000/api - All API endpoints base path

๐Ÿ” Authenticationโ€‹

Currently, the API operates in development mode without authentication. Future versions will include:

  • JWT token-based authentication
  • Role-based access control (Admin, Manager, Employee)
  • API key authentication for third-party integrations

๐Ÿ“Š Response Formatโ€‹

All API responses follow a consistent format:

Success Responseโ€‹

{
"success": true,
"data": {...},
"count": 10,
"message": "Operation successful"
}

Error Responseโ€‹

{
"success": false,
"message": "Error description",
"error": "Detailed error information",
"statusCode": 400
}

๐ŸŽฏ Available Endpointsโ€‹

Core Resourcesโ€‹

ResourceBase EndpointDescription
Movies/api/moviesMovie catalog management
Sessions/api/sessionsMovie session scheduling
Tickets/api/ticketsTicket sales and management
Sales/api/salesPOS and transaction management

System Endpointsโ€‹

EndpointMethodDescription
/healthGETSystem health check
/apiGETAPI information and endpoints

๐ŸŽฌ Movies APIโ€‹

Complete CRUD operations for movie management.

Endpoints Overviewโ€‹

EndpointMethodDescription
/api/moviesGETList all movies with filters
/api/moviesPOSTCreate new movie
/api/movies/:idGETGet movie by ID
/api/movies/:idPUTUpdate movie
/api/movies/:idDELETEDelete/deactivate movie
/api/movies/:id/activatePATCHActivate movie
/api/movies/:id/statsGETGet movie statistics
/api/movies/searchGETSearch movies by title

Movie Data Modelโ€‹

{
"id": 1,
"title": "Avatar: The Way of Water",
"duration_min": 192,
"genre": "Sci-Fi/Action",
"description": "Set more than a decade after the events of the first film...",
"rating": "PG-13",
"poster_url": "https://example.com/posters/avatar2.jpg",
"is_active": true,
"created_at": "2025-09-14T17:28:38.496Z",
"updated_at": "2025-09-14T17:28:38.496Z",
"total_sessions": "5",
"upcoming_sessions": "3"
}

Quick Examplesโ€‹

Get All Moviesโ€‹

curl -X GET "http://localhost:3000/api/movies"

Create Movieโ€‹

curl -X POST "http://localhost:3000/api/movies" \
-H "Content-Type: application/json" \
-d '{
"title": "New Movie",
"duration_min": 120,
"genre": "Action",
"description": "An exciting new movie",
"rating": "PG-13"
}'

Search Moviesโ€‹

curl -X GET "http://localhost:3000/api/movies/search?title=Avatar"

๐ŸŽญ Sessions APIโ€‹

Movie session scheduling and seat management.

Endpoints Overviewโ€‹

EndpointMethodDescription
/api/sessionsGETList all sessions
/api/sessionsPOSTCreate new session
/api/sessions/:idGETGet session details
/api/sessions/:idPUTUpdate session
/api/sessions/:idDELETEDelete session
/api/sessions/:id/seatsGETGet seat availability

Quick Examplesโ€‹

Get All Sessionsโ€‹

curl -X GET "http://localhost:3000/api/sessions"

Get Session Seatsโ€‹

curl -X GET "http://localhost:3000/api/sessions/1/seats"

๐ŸŽซ Tickets APIโ€‹

Ticket sales and management system.

Endpoints Overviewโ€‹

EndpointMethodDescription
/api/ticketsGETList all tickets
/api/ticketsPOSTCreate single ticket
/api/tickets/bulkPOSTCreate multiple tickets
/api/tickets/:idGETGet ticket details
/api/tickets/:idDELETECancel ticket

Quick Examplesโ€‹

Buy Single Ticketโ€‹

curl -X POST "http://localhost:3000/api/tickets" \
-H "Content-Type: application/json" \
-d '{
"session_id": 1,
"seat_id": "A05",
"price": 25.00
}'

Buy Multiple Ticketsโ€‹

curl -X POST "http://localhost:3000/api/tickets/bulk" \
-H "Content-Type: application/json" \
-d '{
"session_id": 1,
"seat_ids": ["A05", "A06", "A07"],
"price": 25.00
}'

๐Ÿ›’ Sales APIโ€‹

Point of Sale system for concessions and transactions.

Endpoints Overviewโ€‹

EndpointMethodDescription
/api/salesGETList all sales
/api/salesPOSTCreate new sale
/api/sales/:idGETGet sale details
/api/sales/:id/itemsPOSTAdd item to sale
/api/sales/:id/discountPOSTApply discount
/api/sales/:id/finalizePOSTComplete sale
/api/sales/:id/cancelPOSTCancel sale

๐Ÿ“ˆ Rate Limitingโ€‹

The API implements rate limiting to ensure fair usage:

Endpoint TypeLimitWindow
General100 requests15 minutes
Tickets20 requests5 minutes
Sales50 requests10 minutes

Rate limit headers included in responses:

RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 1640123456

๐Ÿ”ง Error Handlingโ€‹

Common HTTP Status Codesโ€‹

CodeStatusDescription
200OKSuccess
201CreatedResource created
400Bad RequestValidation error
404Not FoundResource not found
409ConflictResource conflict (e.g., seat taken)
429Too Many RequestsRate limit exceeded
500Internal ErrorServer error

Validation Errorsโ€‹

Validation errors return detailed information:

{
"success": false,
"message": "Validation error",
"errors": [
"\"title\" is required",
"\"duration_min\" must be a positive number"
]
}

๐Ÿงช Testing the APIโ€‹

Using cURLโ€‹

Most examples in this documentation use cURL. Make sure the API server is running:

# Check if API is running
curl http://localhost:3000/health

# Get API information
curl http://localhost:3000/api

Using Postmanโ€‹

  1. Import the OpenAPI/Swagger specification from http://localhost:3000/api
  2. Set base URL to http://localhost:3000
  3. Test endpoints using the imported collection

Interactive Testingโ€‹

Visit http://localhost:3000/api in your browser for an interactive API explorer.

๐Ÿš€ Getting Startedโ€‹

  1. Start the API server:

    cd backstage_backend
    make up
  2. Verify it's running:

    curl http://localhost:3000/health
  3. Explore available endpoints:

    curl http://localhost:3000/api
  4. Test with a simple request:

    curl http://localhost:3000/api/movies

๐Ÿ“š Additional Resourcesโ€‹

For detailed endpoint documentation with request/response schemas, visit the interactive Swagger UI at http://localhost:3000/api/docs when the server is running.

๐Ÿ”ง Swagger UI Featuresโ€‹

The interactive API documentation includes:

  • Live API Testing: Test endpoints directly from the browser
  • Request/Response Examples: See actual data formats
  • Schema Validation: Understand required fields and data types
  • Authentication Testing: Test secured endpoints (when implemented)
  • Response Codes: Complete HTTP status code documentation

Browser Compatibilityโ€‹

The Swagger UI is optimized for:

  • โœ… Chrome/Chromium: Full compatibility
  • โœ… Firefox: Full compatibility
  • โœ… Safari: Compatible with relaxed security policies for development
  • โœ… Edge: Full compatibility

Accessing Swagger UIโ€‹

  1. Ensure the backend server is running: make up
  2. Open your browser to: http://localhost:3000/api/docs
  3. Explore and test the Movie API endpoints interactively