API Specifications

API Specifications

Overview

RunOn! API is built on AWS API Gateway with Lambda functions, integrating various Google APIs and other services.

Authentication

• Provider: Auth0
• Type: JWT Bearer tokens
• Flows: OAuth 2.0 with social login support

External API Integrations

Google Search API

{
  "endpoint": "https://api.google.com/search",
  "parameters": {
    "query": "running events near {location}",
    "type": "event",
    "radius": "number (km)"
  },
  "response": {
    "events": [{
      "title": "string",
      "date": "ISO8601",
      "location": {
        "lat": "number",
        "lng": "number",
        "address": "string"
      },
      "description": "string",
      "url": "string"
    }]
  }
}

Google Places API

{
  "endpoint": "https://maps.googleapis.com/maps/api/place",
  "methods": {
    "nearby": "/nearbysearch/json",
    "details": "/details/json"
  },
  "parameters": {
    "location": "lat,lng",
    "radius": "number",
    "type": "event_venue"
  }
}

Google Calendar API

{
  "endpoint": "https://www.googleapis.com/calendar/v3",
  "methods": {
    "events": {
      "insert": "POST /calendars/{calendarId}/events",
      "list": "GET /calendars/{calendarId}/events",
      "update": "PUT /calendars/{calendarId}/events/{eventId}"
    }
  }
}

RunOn! API Endpoints

Events

/api/v1/events:
  get:
    description: Get events based on location and preferences
    parameters:
      - name: location
        in: query
        required: true
      - name: radius
        in: query
        default: 50
      - name: types
        in: query
        description: Event types to include
    responses:
      200:
        description: List of events
        schema: EventList
      401:
        description: Unauthorized
      403:
        description: Forbidden

  post:
    description: Save event to user's calendar
    parameters:
      - name: eventId
        in: body
        required: true
    responses:
      201:
        description: Event saved
      401:
        description: Unauthorized

User Preferences

/api/v1/preferences:
  get:
    description: Get user preferences
    responses:
      200:
        description: User preferences
        schema: UserPreferences
      401:
        description: Unauthorized

  put:
    description: Update user preferences
    parameters:
      - name: preferences
        in: body
        required: true
        schema: UserPreferences
    responses:
      200:
        description: Preferences updated
      401:
        description: Unauthorized

Data Models

Event

interface Event {
  id: string;
  title: string;
  description: string;
  date: ISO8601String;
  location: {
    lat: number;
    lng: number;
    address: string;
  };
  type: EventType;
  url: string;
  source: 'google' | 'manual' | 'partner';
}

UserPreferences

interface UserPreferences {
  location: {
    lat: number;
    lng: number;
    radius: number;
  };
  eventTypes: EventType[];
  notifications: boolean;
  calendar: {
    sync: boolean;
    calendarId?: string;
  };
}

Rate Limiting

• Standard tier: 60 requests per minute
• Premium tier: 300 requests per minute

Caching

• Redis cache for frequently accessed data
• Cache invalidation: 15 minutes for event listings
• Persistent cache for static data

Error Handling

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "object (optional)"
  }
}

API Versioning

• Version in URL path (/api/v1/)
• Semantic versioning
• Backward compatibility guaranteed within major version

Security

• HTTPS only
• JWT validation
• Rate limiting
• Request signing for premium features