Trip Plan API - tomassirio/wanderer-backend GitHub Wiki

Trip Plan API

The Trip Plan API allows you to create, update, and delete trip plans that define your intended route and waypoints.

Command Operations (Port 8081)

Base URL: http://localhost:8081/api/1/trips/plans

Authentication: Required (USER or ADMIN role)

Create Trip Plan

Create a new trip plan with route details and waypoints.

Endpoint: POST /api/1/trips/plans

Request Body

{
  "name": "Camino Francés Plan",
  "planType": "MULTI_DAY",
  "startLocation": {
    "latitude": 43.1631,
    "longitude": -1.2350
  },
  "endLocation": {
    "latitude": 42.8805,
    "longitude": -8.5457
  },
  "startDate": "2025-11-01T08:00:00Z",
  "endDate": "2025-12-15T18:00:00Z",
  "metadata": {
    "dailyDistance": 25,
    "restDays": [7, 14, 21],
    "waypoints": [
      {
        "name": "Pamplona",
        "location": {"latitude": 42.8125, "longitude": -1.6458},
        "day": 3
      },
      {
        "name": "Logroño",
        "location": {"latitude": 42.4627, "longitude": -2.4450},
        "day": 7
      },
      {
        "name": "Burgos",
        "location": {"latitude": 42.3439, "longitude": -3.6967},
        "day": 12
      },
      {
        "name": "León",
        "location": {"latitude": 42.5987, "longitude": -5.5671},
        "day": 21
      }
    ]
  }
}
Field Type Required Description
name string Yes Plan name
planType enum Yes SIMPLE or MULTI_DAY
startLocation GeoLocation Yes Starting coordinates
endLocation GeoLocation Yes Destination coordinates
startDate ISO 8601 No Planned start date/time
endDate ISO 8601 No Planned end date/time
metadata JSON No Flexible plan data (waypoints, notes, etc.)

Plan Types:

  • SIMPLE: Direct point-to-point plan without waypoints
  • MULTI_DAY: Multi-day journey with waypoints and daily stages

Response

Status: 201 Created

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Camino Francés Plan",
  "planType": "MULTI_DAY",
  "startLocation": {
    "latitude": 43.1631,
    "longitude": -1.2350
  },
  "endLocation": {
    "latitude": 42.8805,
    "longitude": -8.5457
  },
  "startDate": "2025-11-01T08:00:00Z",
  "endDate": "2025-12-15T18:00:00Z",
  "metadata": {
    "dailyDistance": 25,
    "restDays": [7, 14, 21],
    "waypoints": [...]
  },
  "creationTimestamp": "2025-10-16T10:30:00Z",
  "updateTimestamp": "2025-10-16T10:30:00Z"
}

Example

curl -X POST http://localhost:8081/api/1/trips/plans \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camino Francés Plan",
    "planType": "MULTI_DAY",
    "startLocation": {"latitude": 43.1631, "longitude": -1.2350},
    "endLocation": {"latitude": 42.8805, "longitude": -8.5457},
    "startDate": "2025-11-01T08:00:00Z"
  }'

Update Trip Plan

Update an existing trip plan.

Endpoint: PUT /api/1/trips/plans/{planId}

Path Parameters

Parameter Type Description
planId UUID Plan's unique identifier

Request Body

Same structure as Create Trip Plan. All fields are optional, but at least one should be provided.

{
  "name": "Updated Plan Name",
  "startDate": "2025-11-05T08:00:00Z",
  "metadata": {
    "dailyDistance": 30,
    "note": "Increased daily distance"
  }
}

Response

Status: 200 OK

Returns the updated trip plan object.

Example

curl -X PUT http://localhost:8081/api/1/trips/plans/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Camino Plan",
    "startDate": "2025-11-05T08:00:00Z"
  }'

Delete Trip Plan

Delete a trip plan and all associated data.

Endpoint: DELETE /api/1/trips/plans/{planId}

Path Parameters

Parameter Type Description
planId UUID Plan's unique identifier

Response

Status: 204 No Content

Example

curl -X DELETE http://localhost:8081/api/1/trips/plans/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <your-token>"

Query Operations (Port 8082)

Base URL: http://localhost:8082/api/1/trips/plans

Get Trip Plan by ID

Retrieve a specific trip plan.

Endpoint: GET /api/1/trips/plans/{planId}

Authentication: Required (USER or ADMIN role)

Path Parameters

Parameter Type Description
planId UUID Plan's unique identifier

Response

Status: 200 OK

Returns the trip plan object.

Example

curl -X GET http://localhost:8082/api/1/trips/plans/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <your-token>"

Get Trip Plans for User

Retrieve all trip plans for the authenticated user.

Endpoint: GET /api/1/trips/plans/me

Authentication: Required (USER or ADMIN role)

Response

Status: 200 OK

Returns an array of trip plan objects.

Example

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

Metadata Structure

The metadata field is a flexible JSON object that can store any plan-specific data. Here are some common patterns:

Simple Plan Metadata

{
  "notes": "Direct route to Santiago",
  "estimatedDays": 30,
  "difficulty": "moderate"
}

Multi-Day Plan Metadata

{
  "dailyDistance": 25,
  "restDays": [7, 14, 21, 28],
  "accommodations": [
    {
      "name": "Albergue Municipal",
      "location": {"latitude": 42.8125, "longitude": -1.6458},
      "day": 3,
      "phone": "+34 948 123 456"
    }
  ],
  "waypoints": [
    {
      "name": "Pamplona",
      "location": {"latitude": 42.8125, "longitude": -1.6458},
      "day": 3,
      "description": "Historic city, running of the bulls"
    },
    {
      "name": "Logroño", 
      "location": {"latitude": 42.4627, "longitude": -2.4450},
      "day": 7,
      "description": "Wine region capital"
    }
  ],
  "notes": "Following the traditional Camino Francés route"
}

Custom Metadata Examples

For cyclists:

{
  "mode": "bicycle",
  "dailyDistance": 80,
  "elevation": {
    "totalAscent": 12000,
    "highestPoint": 1505
  },
  "bikeFriendly": true
}

For hikers:

{
  "mode": "walking",
  "difficulty": "moderate",
  "terrain": ["mountains", "plains", "urban"],
  "equipment": ["hiking boots", "backpack", "poles"],
  "waterSources": [
    {"location": {...}, "type": "fountain"},
    {"location": {...}, "type": "stream"}
  ]
}

Linking Trip Plans to Trips

When creating a trip, you can reference a trip plan using the tripPlanId field:

# 1. Create a trip plan
PLAN_RESPONSE=$(curl -X POST http://localhost:8081/api/1/trips/plans \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Camino Plan",
    "planType": "MULTI_DAY",
    "startLocation": {"latitude": 43.1631, "longitude": -1.2350},
    "endLocation": {"latitude": 42.8805, "longitude": -8.5457}
  }')

PLAN_ID=$(echo $PLAN_RESPONSE | jq -r '.id')

# 2. Create a trip using the plan
curl -X POST http://localhost:8081/api/1/trips \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"My Camino Journey\",
    \"tripPlanId\": \"$PLAN_ID\",
    \"visibility\": \"PUBLIC\"
  }"

Error Responses

404 Not Found

Plan doesn't exist or you don't have access:

{
  "timestamp": "2025-10-16T10:30:00.000Z",
  "status": 404,
  "error": "Not Found",
  "message": "Trip plan not found",
  "path": "/api/1/trips/plans/880e8400-e29b-41d4-a716-446655440000"
}

403 Forbidden

Cannot modify someone else's plan:

{
  "timestamp": "2025-10-16T10:30:00.000Z",
  "status": 403,
  "error": "Forbidden",
  "message": "You don't have permission to modify this trip plan",
  "path": "/api/1/trips/plans/880e8400-e29b-41d4-a716-446655440000"
}

Best Practices

Plan Naming

  • Use descriptive names that identify the route
  • Include the route name or key destinations
  • Examples: "Camino Francés", "Utrecht to Santiago", "Portuguese Coastal Route"

Waypoint Selection

  • Include major cities and landmarks
  • Add accommodation stops
  • Mark rest days
  • Include points of interest

Metadata Usage

  • Store structured data that your application will use
  • Include information useful for planning and navigation
  • Document your metadata schema for consistency

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** ⚠️