Hiking-Logbook

API Specification

This document provides a comprehensive specification for the Hiking Logbook API endpoints, request/response formats, and authentication mechanisms.

Overview

The Hiking Logbook API is a RESTful service built with Express.js that provides:

Sprint 1 Scope

Current Implementation Focus:

Authentication

JWT Token Format

All protected endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

Token Structure

{
  "uid": "user_firebase_uid",
  "email": "user@example.com",
  "iat": 1640995200,
  "exp": 1641081600
}

API Endpoints

Base URL

Development: http://localhost:3000
Production: https://your-api-domain.com

Sprint 1: Authentication Endpoints

POST /auth/signup

Creates a new user account and basic profile.

Request:

{
  "email": "user@example.com",
  "password": "securepassword123",
  "displayName": "John Doe"
}

Response (Success - 201):

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "uid": "firebase_generated_uid",
    "email": "user@example.com",
    "displayName": "John Doe",
    "token": "jwt_token_here"
  }
}

Response (Error - 400):

{
  "success": false,
  "error": "Validation failed",
  "details": [
    "Email is required",
    "Password must be at least 8 characters"
  ]
}

Response (Error - 409):

{
  "success": false,
  "error": "User already exists"
}

Validation Rules:

POST /auth/login

Authenticates existing user and returns JWT token.

Request:

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (Success - 200):

{
  "success": true,
  "message": "Login successful",
  "data": {
    "uid": "firebase_generated_uid",
    "email": "user@example.com",
    "displayName": "John Doe",
    "token": "jwt_token_here"
  }
}

Response (Error - 401):

{
  "success": false,
  "error": "Invalid credentials"
}

Response (Error - 404):

{
  "success": false,
  "error": "User not found"
}

POST /auth/verify

Verifies JWT token validity.

Request:

{
  "token": "jwt_token_here"
}

Response (Success - 200):

{
  "success": true,
  "message": "Token is valid",
  "data": {
    "uid": "firebase_generated_uid",
    "email": "user@example.com",
    "displayName": "John Doe"
  }
}

Response (Error - 401):

{
  "success": false,
  "error": "Invalid or expired token"
}

POST /auth/logout

Logs out user (client-side token removal).

Request:

// No body required, just valid JWT token in header
Authorization: Bearer <jwt_token>

Response (Success - 200):

{
  "success": true,
  "message": "Logout successful"
}

Response (Error - 401):

{
  "success": false,
  "error": "Invalid or expired token"
}

Sprint 1: Basic User Profile Endpoints

GET /users/profile

Retrieves the current user’s basic profile information.

Headers:

Authorization: Bearer <jwt_token>

Response (Success - 200):

{
  "success": true,
  "data": {
    "uid": "firebase_generated_uid",
    "email": "user@example.com",
    "displayName": "John Doe",
    "bio": "Hiking enthusiast from Colorado",
    "photoURL": "https://example.com/photo.jpg",
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:45:00.000Z"
  }
}

Response (Error - 401):

{
  "success": false,
  "error": "Unauthorized - Invalid or missing token"
}

PUT /users/profile

Updates the current user’s basic profile information.

Headers:

Authorization: Bearer <jwt_token>
Content-Type: application/json

Request:

{
  "displayName": "John Smith",
  "bio": "Updated bio information",
  "photoURL": "https://example.com/new-photo.jpg"
}

Response (Success - 200):

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "uid": "firebase_generated_uid",
    "updatedAt": "2024-01-20T15:00:00.000Z"
  }
}

Response (Error - 400):

{
  "success": false,
  "error": "Validation failed",
  "details": [
    "Display name must be between 2 and 50 characters"
  ]
}

Sprint 1: Technical Implementation

JWT Configuration

Basic Firebase Security Rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Users can only access their own profile
    match /users/{userId} {
      allow read, write: if request.auth != null &&
        request.auth.uid == userId;
    }
  }
}

Sprint 1: Basic Error Handling

Standard Error Response Format

{
  "success": false,
  "error": "Error message",
  "details": ["Additional error details"],
  "timestamp": "2024-01-20T15:00:00.000Z"
}

HTTP Status Codes (Sprint 1)

Common Error Messages (Sprint 1)

// Authentication Errors
"Invalid credentials";
"User not found";
"User already exists";
"Invalid or expired token";
"Unauthorized - Invalid or missing token";

// Validation Errors
"Email is required";
"Password must be at least 8 characters";
"Display name must be between 2 and 50 characters";

// Server Errors
"Internal server error";
"Database connection failed";

Sprint 1: Basic Testing

Test with curl

# Test signup
curl -X POST http://localhost:3000/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123","displayName":"Test User"}'

# Test login
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

# Test protected endpoint
curl -X GET http://localhost:3000/users/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Support

Getting Help

  1. Check this specification document
  2. Review the Development API Setup guide
  3. Check the Running Locally troubleshooting section
  4. Contact the development team

This API specification focuses on Sprint 1 implementation. For additional features, check the main README.