Favorites

Save and manage frequently used routes (requires authentication)

Overview

The favorites endpoints allow authenticated users to save frequently used routes for quick access. Each user can save up to 10 favorite routes.

All favorites endpoints require authentication. See Authentication for details.

Get Favorites

Request

GET /api/favorites
Authorization: Bearer x9y8z7w6v5u4...

Headers

Authorization · string · required

Bearer token obtained from authentication

Response Fields

count · number

Number of saved favorites for this user

favorites · object[]

Array of favorite route objects

Show Favorite Properties

id · string

Unique favorite identifier (UUID)

label · string

User-provided name for this favorite

from · string

Origin node ID

to · string

Destination node ID

defaultTime · string

Default departure time in HH:MM format

createdAt · string

ISO 8601 timestamp of when favorite was created

Create Favorite

Request

POST /api/favorites
Authorization: Bearer x9y8z7w6v5u4...
Content-Type: application/json

{
  "label": "Morning Commute",
  "from": "TILAGOR",
  "to": "CAMPUS",
  "defaultTime": "08:00"
}

Headers

Authorization · string · required

Bearer token obtained from authentication

Request Body

label · string · required

User-friendly name for this favorite route

Example: “Morning Commute”, “Weekend Shopping”

from · string · required

Origin node ID. Must be a valid node.

Example: TILAGOR, CAMPUS

to · string · required

Destination node ID. Must be a valid node.

Example: CAMPUS, MEDICAL

defaultTime · string

Default departure time in HH:MM format. Defaults to “08:00” if not provided.

Example: 08:30, 17:00

Response Fields

success · boolean

Indicates if the favorite was saved successfully

message · string

Confirmation message

favorite · object

The created favorite object with generated ID and timestamp

Error Responses

Missing Required Fields (400)

{
  "error": "Missing required fields",
  "message": "Please provide label, from, and to"
}

Duplicate Favorite (409)

{
  "error": "Duplicate favorite",
  "message": "This route is already saved",
  "existing": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "label": "Morning Commute"
  }
}

Limit Reached (400)

{
  "error": "Limit reached",
  "message": "Maximum 10 favorites allowed. Please delete some to add more."
}

Update Favorite

Request

PUT /api/favorites/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer x9y8z7w6v5u4...
Content-Type: application/json

{
  "label": "Early Morning Commute",
  "defaultTime": "07:30"
}

Path Parameters

id · string · required

Favorite ID (UUID)

Headers

Authorization · string · required

Bearer token obtained from authentication

Request Body

label · string

Updated label for the favorite

defaultTime · string

Updated default time in HH:MM format

The from and to fields cannot be updated. Create a new favorite if you need a different route.

Error Responses

Not Found (404)

{
  "error": "Not found",
  "message": "Favorite not found or does not belong to you"
}

Delete Favorite

Request

DELETE /api/favorites/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer x9y8z7w6v5u4...

Path Parameters

id · string · required

Favorite ID (UUID)

Headers

Authorization · string · required

Bearer token obtained from authentication

Error Responses

Not Found (404)

{
  "error": "Not found",
  "message": "Favorite not found or does not belong to you"
}

Usage Examples

Save Morning Commute

curl -X POST http://localhost:3000/api/favorites \
  -H "Authorization: Bearer x9y8z7w6v5u4..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Morning Class",
    "from": "TILAGOR",
    "to": "CAMPUS",
    "defaultTime": "08:00"
  }'

Quick Route Planning with Favorites

# 1. Get favorites
FAVORITES=$(curl -H "Authorization: Bearer x9y8z7w6v5u4..." \
  http://localhost:3000/api/favorites)

# 2. Extract first favorite's from, to, and defaultTime
FROM=$(echo $FAVORITES | jq -r '.favorites[0].from')
TO=$(echo $FAVORITES | jq -r '.favorites[0].to')
TIME=$(echo $FAVORITES | jq -r '.favorites[0].defaultTime')

# 3. Plan route
curl "http://localhost:3000/api/routes?from=$FROM&to=$TO&time=$TIME"

Update Multiple Favorites

# Get all favorites
FAVS=$(curl -H "Authorization: Bearer TOKEN" \
  http://localhost:3000/api/favorites)

# Update each one's default time
echo $FAVS | jq -r '.favorites[].id' | while read ID; do
  curl -X PUT http://localhost:3000/api/favorites/$ID \
    -H "Authorization: Bearer TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"defaultTime": "08:00"}'
done

Favorite Limits

Each user can save up to 10 favorites. This limit prevents database bloat and encourages users to save only their most frequent routes.

Why 10 Favorites?

• Most users have 3-5 regular routes
• 10 allows flexibility for occasional routes
• Keeps the favorites list manageable
• Reduces server storage requirements

Data Persistence

Favorites are stored in the server-side JSON file:

src/data/favorites.json

In the current implementation, favorites are stored in a JSON file. For production, migrate to a proper database (PostgreSQL, MongoDB, etc.) for better reliability and scalability.

Security

User Isolation

Each user can only access their own favorites:

const userFavorites = data.favorites.filter(
  f => f.userId === user.id
);

Duplicate Prevention

The API prevents duplicate favorites for the same from/to combination:

const duplicate = data.favorites.find(
  f => f.userId === user.id && 
       f.from === from && 
       f.to === to
);

Related Endpoints

Authentication

Get auth token for favorites

Route Planning

Use favorites with route planning

Nodes

Valid from/to node IDs

Profile

View user information