API Reference

Relevant source files - app.js - config/swagger.js - routes/auth.routes.js - routes/subscription.routes.js - routes/user.routes.js - routes/workflow.routes.js

The Subscription Tracker API provides a RESTful interface for managing user accounts, tracking recurring subscriptions, and automating renewal notifications. The API is versioned under /api/v1 and follows standard HTTP conventions for status codes and methods.

Base Configuration

All endpoints are prefixed with /api/v1 as defined in the main application entry point app.js27-31 The server supports Cross-Origin Resource Sharing (CORS) and parses JSON request bodies app.js20-21

API Architecture Overview The following diagram maps the logical API domains to their respective route handlers in the codebase.

Title: API Domain Mapping

[Flowchart Diagram]

Sources: app.js27-31 routes/auth.routes.js4 routes/user.routes.js11 routes/subscription.routes.js14 routes/workflow.routes.js46 routes/test.routes.js5

Authentication API

The Authentication domain handles user identity through registration, login, and logout. It utilizes JWT (JSON Web Tokens) for stateless session management.

POST/api/v1/auth/sign-up: Creates a new user with a hashed password routes/auth.routes.js36
POST/api/v1/auth/sign-in: Authenticates credentials and returns a Bearer token routes/auth.routes.js65
POST/api/v1/auth/sign-out: Ends the user session routes/auth.routes.js79

For details on token issuance and security, see Authentication API.

User Management API

Provides CRUD operations for user profiles. Most endpoints in this domain are protected by the authorize middleware, requiring a valid JWT routes/user.routes.js27-52

GET/api/v1/users: List all users (Protected) routes/user.routes.js27
GET/api/v1/users/:id: Fetch specific user details routes/user.routes.js52
PUT/api/v1/users/:id: Update user information routes/user.routes.js115
DELETE/api/v1/users/:id: Remove a user account routes/user.routes.js139

For details on data sanitization and authorization guards, see User Management API.

Subscription API

The core of the application, managing the lifecycle of recurring payments. Creating a subscription automatically triggers an asynchronous background workflow for reminders routes/subscription.routes.js82

POST/api/v1/subscriptions: Create a new subscription and trigger Upstash workflow routes/subscription.routes.js82
GET/api/v1/subscriptions/user/:id: Retrieve all subscriptions belonging to a specific user routes/subscription.routes.js160
GET/api/v1/subscriptions/upcoming-renewals: Query subscriptions nearing their renewal date routes/subscription.routes.js193

For details on ownership logic and workflow triggers, see Subscription API.

Workflow and Test APIs

These endpoints handle the integration with Upstash for scheduled tasks and provide diagnostic tools for developers.

POST/api/v1/workflows/subscription/reminder: The callback URL for the Upstash workflow engine routes/workflow.routes.js70
POST/api/v1/test/send-reminder-email: A manual trigger to verify the email transporter and templates routes/test.routes.js20

For details on the workflow state machine and email testing, see Workflow and Test APIs.

API Documentation and Health

The API includes built-in documentation and health monitoring.

Title: Documentation and Health Infrastructure

[Flowchart Diagram]

Health Check: Accessible at /api/v1/health, returning uptime and environment status app.js44-51
Swagger UI: Interactive documentation is available at /api-docs/v1/, generated from JSDoc comments in route files app.js32-40 config/swagger.js29

Sources: app.js44-51 app.js32-40 config/swagger.js4-32