chat/docs/API.md

API Documentation - Women's Safety App

Overview

The Women's Safety App provides a comprehensive API for managing user profiles, emergency alerts, location services, and health calendar functionality.

Base URL: http://localhost:8000 (API Gateway)

Authentication

All endpoints except registration and login require JWT authentication.

Headers:

Authorization: Bearer <jwt_token>

API Endpoints

🔐 Authentication

Register User

POST /api/v1/register

Body:

{
  "email": "user@example.com",
  "password": "password123",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890"
}

Login

POST /api/v1/login

Body:

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

Response:

{
  "access_token": "jwt_token_here",
  "token_type": "bearer"
}

👤 User Profile

Get Profile

GET /api/v1/profile
Authorization: Bearer <token>

Update Profile

PUT /api/v1/profile
Authorization: Bearer <token>

Body:

{
  "first_name": "Jane",
  "bio": "Updated bio",
  "emergency_contact_1_name": "Emergency Contact",
  "emergency_contact_1_phone": "+1234567890"
}

🚨 Emergency Services

Create Emergency Alert

POST /api/v1/alert
Authorization: Bearer <token>

Body:

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "alert_type": "general",
  "message": "Need help immediately",
  "address": "123 Main St, City"
}

Respond to Alert

POST /api/v1/alert/{alert_id}/respond
Authorization: Bearer <token>

Body:

{
  "response_type": "help_on_way",
  "message": "I'm coming to help",
  "eta_minutes": 10
}

Resolve Alert

PUT /api/v1/alert/{alert_id}/resolve
Authorization: Bearer <token>

Get My Alerts

GET /api/v1/alerts/my
Authorization: Bearer <token>

Get Active Alerts

GET /api/v1/alerts/active
Authorization: Bearer <token>

📍 Location Services

Update Location

POST /api/v1/update-location
Authorization: Bearer <token>

Body:

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "accuracy": 10.5
}

Get User Location

GET /api/v1/user-location/{user_id}
Authorization: Bearer <token>

Find Nearby Users

GET /api/v1/nearby-users?latitude=37.7749&longitude=-122.4194&radius_km=1.0
Authorization: Bearer <token>

Get Location History

GET /api/v1/location-history?hours=24
Authorization: Bearer <token>

📅 Calendar Services

Create Calendar Entry

POST /api/v1/entries
Authorization: Bearer <token>

Body:

{
  "entry_date": "2024-01-15",
  "entry_type": "period",
  "flow_intensity": "medium",
  "mood": "happy",
  "energy_level": 4
}

Get Calendar Entries

GET /api/v1/entries?start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

Get Cycle Overview

GET /api/v1/cycle-overview
Authorization: Bearer <token>

Response:

{
  "current_cycle_day": 15,
  "current_phase": "luteal",
  "next_period_date": "2024-02-01",
  "days_until_period": 7,
  "cycle_regularity": "regular",
  "avg_cycle_length": 28
}

Get Health Insights

GET /api/v1/insights
Authorization: Bearer <token>

🔔 Notification Services

Register Device Token

POST /api/v1/register-device
Authorization: Bearer <token>

Body:

{
  "token": "fcm_device_token_here",
  "platform": "android"
}

Send Notification

POST /api/v1/send-notification?target_user_id=123
Authorization: Bearer <token>

Body:

{
  "title": "Hello!",
  "body": "This is a test notification",
  "priority": "normal"
}

📊 System Status

Check Service Health

GET /api/v1/health

Check All Services Status

GET /api/v1/services-status

Error Responses

All endpoints return errors in the following format:

{
  "detail": "Error message here"
}

Common HTTP Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 422 - Validation Error
• 429 - Rate Limited
• 500 - Internal Server Error
• 503 - Service Unavailable

Rate Limiting

API Gateway implements rate limiting:

• 100 requests per minute per IP address
• Emergency endpoints have higher priority

Data Models

User

{
  "id": 1,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",
  "location_sharing_enabled": true,
  "emergency_notifications_enabled": true,
  "email_verified": false,
  "is_active": true
}

Emergency Alert

{
  "id": 1,
  "uuid": "550e8400-e29b-41d4-a716-446655440001",
  "user_id": 1,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "alert_type": "general",
  "message": "Need help",
  "is_resolved": false,
  "notified_users_count": 15,
  "responded_users_count": 3,
  "created_at": "2024-01-15T10:30:00Z"
}

Location

{
  "user_id": 1,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "accuracy": 10.5,
  "updated_at": "2024-01-15T10:30:00Z"
}

WebSocket Events (Future Enhancement)

Real-time notifications for emergency alerts:

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8000/ws/alerts');

// Listen for emergency alerts
ws.onmessage = function(event) {
    const alert = JSON.parse(event.data);
    // Handle emergency alert
};

SDK Examples

JavaScript/TypeScript

class WomenSafetyAPI {
  constructor(baseUrl, token) {
    this.baseUrl = baseUrl;
    this.token = token;
  }

  async createAlert(alertData) {
    const response = await fetch(`${this.baseUrl}/api/v1/alert`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify(alertData)
    });
    return response.json();
  }
}

Python

import httpx

class WomenSafetyAPI:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url
        self.headers = {"Authorization": f"Bearer {token}"}

    async def create_alert(self, alert_data: dict):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/api/v1/alert",
                json=alert_data,
                headers=self.headers
            )
            return response.json()