API Overview - tomassirio/wanderer-backend GitHub Wiki

API Overview

Introduction

The Trip Tracker Backend provides a comprehensive RESTful API for managing trips, tracking locations, and engaging with trip updates through comments and reactions. The system is built using CQRS (Command Query Responsibility Segregation) architecture to optimize read and write operations independently.

Architecture

CQRS Pattern

The application is split into three separate services:

  1. tracker-auth (Port 8083): Handles authentication and user registration
  2. tracker-command (Port 8081): Processes all write operations (commands)
  3. tracker-query (Port 8082): Handles all read operations (queries)

Why CQRS?

  • Performance: Read and write operations can be optimized independently
  • Scalability: Query and command services can be scaled separately based on load
  • Flexibility: Different data models for reading and writing
  • Clear Separation: Commands change state, queries don't

Base URLs

When running locally with default configuration:

Authentication Service: http://localhost:8083
Command Service:        http://localhost:8081
Query Service:          http://localhost:8082

All API endpoints are versioned and prefixed with /api/1.

Request/Response Format

Content Type

All requests and responses use JSON format:

Content-Type: application/json

Authentication Header

Most endpoints require JWT authentication:

Authorization: Bearer <jwt-token>

Standard Response Structure

Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Trip",
  ...additional fields
}

Error Response

{
  "timestamp": "2025-10-16T10:30:00.000Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed for field 'name'",
  "path": "/api/1/trips"
}

HTTP Methods

The API follows REST conventions:

Method Purpose Idempotent
GET Retrieve resources Yes
POST Create new resources No
PUT Update entire resource Yes
PATCH Partial update No
DELETE Remove resource Yes

HTTP Status Codes

The API uses standard HTTP status codes:

Code Meaning When Used
200 OK Success Successful GET, PUT, PATCH, or DELETE
201 Created Resource created Successful POST
204 No Content Success with no body Successful DELETE
400 Bad Request Invalid input Validation errors
401 Unauthorized Not authenticated Missing or invalid token
403 Forbidden Not authorized Insufficient permissions
404 Not Found Resource not found Invalid ID or resource
409 Conflict Resource conflict Duplicate resource
500 Internal Server Error Server error Unexpected error

Data Types

Common Types

  • UUID: Universally unique identifier, format: 550e8400-e29b-41d4-a716-446655440000
  • ISO 8601 Timestamp: 2025-10-16T10:30:00.000Z
  • GeoLocation: 
    {
  "latitude": 41.8919,
  "longitude": -87.6051,
  "altitude": 200.5
}

Enumerations

Trip Visibility

  • PUBLIC: Visible to everyone
  • PRIVATE: Only visible to owner
  • PROTECTED: Visible to authenticated users

Trip Status

  • CREATED: Trip has been created
  • IN_PROGRESS: Trip is currently active
  • PAUSED: Trip is temporarily paused
  • FINISHED: Trip has been completed

Trip Plan Type

  • SIMPLE: Simple point-to-point plan
  • MULTI_DAY: Multi-day itinerary with waypoints

Reaction Type

  • HEART: ❤️
  • SMILEY: 😊
  • SAD: 😢
  • LAUGH: 😂
  • ANGER: 😠

Pagination

Some endpoints support pagination (to be implemented):

GET /api/1/trips?page=0&size=20&sort=createdAt,desc

Parameters:

  • page: Page number (0-indexed)
  • size: Items per page
  • sort: Sort field and direction

Rate Limiting

Currently, there are no rate limits implemented. This may change in future versions.

Versioning

The API is versioned through the URL path (/api/1). Breaking changes will increment the version number.

Interactive Documentation

Each service provides interactive Swagger/OpenAPI documentation:

These interfaces allow you to:

  • Explore all endpoints
  • View request/response schemas
  • Test endpoints directly from the browser
  • See example payloads

Next Steps

Trip Tracker Backend API Documentation

Welcome to the Trip Tracker Backend API documentation! This wiki provides comprehensive information about all available REST APIs in the system.

📚 Quick Navigation

Getting Started

API References

Reference Guides

🏗️ Architecture Overview

The Trip Tracker Backend follows a CQRS (Command Query Responsibility Segregation) architecture with three main services:

Service Port Purpose Base Path
tracker-auth 8083 Authentication & user registration /api/1/auth
tracker-command 8081 Write operations (Create, Update, Delete) /api/1
tracker-query 8082 Read operations (Queries) /api/1

🔐 Authentication

All API endpoints (except registration and login) require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Get your token by calling the Login endpoint.

🚀 Quick Example

Here's a quick example to get you started:

# 1. Register a new user
curl -X POST http://localhost:8083/api/1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"john","password":"secret123"}'

# 2. Use the returned token to create a trip
curl -X POST http://localhost:8081/api/1/trips \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Camino","visibility":"PUBLIC"}'

# 3. Query your trips
curl -X GET http://localhost:8082/api/1/trips/me \
  -H "Authorization: Bearer <your-token>"

📖 API Documentation

For interactive API documentation with try-it-out functionality, access the Swagger UI:

🤝 Support

For issues, questions, or contributions:

Ready to get started? Check out the Getting Started Guide!

⚠️ **GitHub.com Fallback** ⚠️