Home

SafeRide API Documentation

Welcome to the official SafeRide API documentation! This site provides comprehensive guides, tutorials, and reference materials for integrating with the SafeRide ride-sharing platform.

📚 Tutorials

Step-by-step guides for common integration tasks

📖 API Reference

Interactive Swagger UI documentation (requires API server running)

🔐 Authentication

Coming Soon - JWT authentication guide

⚡ WebSockets

AsyncAPI documentation for real-time updates (requires API server)

Getting Started

1. Authentication

First, authenticate with the API to obtain a JWT token:

POST /api/v1/auth/login
Content-Type: application/json

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

2. Create Resources

Once authenticated, you can create addresses and rides:

POST /api/v1/addresses
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "latitude": 39.4143,
  "longitude": -77.4105,
  "street_number": "122",
  "street_name": "E Patrick St",
  "city": "Frederick",
  "state": "MD",
  "zip": "21705",
  "country": "United States",
  "host_id": 123
}

3. Create a Ride

Use the address IDs to create a ride:

POST /api/v1/rides
Authorization: Bearer <your_jwt_token>
X-Idempotency-Key: <unique-uuid>
Content-Type: application/json

{
  "ride": {
    "vehicle_id": 1,
    "pickup_address_id": 456,
    "dropoff_address_id": 789,
    "payment_method": "card"
  }
}

New to addresses? Check out our tutorial: How to Get an Address ID

View all tutorials →

API Overview

The SafeRide API is a RESTful JSON API that supports:

  • Authentication & Authorization - JWT-based authentication with Rodauth
  • Ride Management - Create, assign, track, and complete rides
  • Address Management - Store and retrieve location data
  • Payment Processing - Stripe integration for secure payments
  • Real-time Updates - WebSocket support via Action Cable
  • Location Tracking - GPS tracking for drivers and riders
  • Notifications - Email and push notifications
  • Analytics - Ride metrics and reporting

Key Features

🚗 Ride Lifecycle Management

Complete ride workflow from request to completion with state transitions, driver assignment, and payment processing.

🌍 Location Services

Geocoding, address validation, and county lookup for US addresses using FCC API.

💳 Payment Integration

Secure payment processing with Stripe, supporting card payments, cash, and donation-only rides.

📡 Real-time Updates

WebSocket connections for live ride status updates, driver location tracking, and instant notifications.

🔒 Security & Authorization

Role-based access control (RBAC) with Pundit policies for passengers, drivers, dispatchers, and admins.

📊 API Standards

RESTful design with JSON:API serialization, idempotency keys, pagination, filtering, and sorting.

Documentation Sections

Core Guides

  • API Documentation - Interactive Swagger UI (requires API server)
  • Authentication Flow (Coming Soon) - JWT authentication guide
  • Testing Guide - Testing patterns and best practices

Integration Guides

Setup Guides

Advanced Topics

API Endpoints

Core Resources

Resource Endpoint Description
Accounts /api/v1/accounts User account management
Addresses /api/v1/addresses Location data management
Rides /api/v1/rides Ride creation and management
Vehicles /api/v1/vehicles Vehicle information
Payments /api/v1/payments Payment processing
Notifications /api/v1/notifications User notifications

Authentication

Endpoint Method Description
/api/v1/auth/login POST Authenticate and receive JWT
/api/v1/auth/logout DELETE Invalidate JWT token
/api/v1/auth/refresh POST Refresh JWT token

Ride Actions

Endpoint Method Description
/api/v1/rides POST Create a new ride
/api/v1/rides/:id GET Get ride details
/api/v1/rides/:id/assign POST Assign driver to ride
/api/v1/rides/:id/start POST Start the ride
/api/v1/rides/:id/complete POST Complete the ride
/api/v1/rides/:id/cancel POST Cancel the ride
/api/v1/rides/:id/eta GET Get estimated time of arrival

Technical Stack

  • Framework: Ruby on Rails 8.0.2 (API-only mode)
  • Database: PostgreSQL with PostGIS extension
  • Authentication: Rodauth with JWT
  • Authorization: Pundit policies
  • Real-time: Action Cable (WebSockets)
  • Payments: Stripe
  • Geocoding: Google Maps API, FCC Area API
  • Background Jobs: Solid Queue
  • Testing: RSpec with Swagger integration

Response Format

All API responses follow the JSON:API specification:

{
  "data": {
    "attributes": {
      "id": 1,
      "status": "requested",
      "created_at": "2025-11-05T12:00:00Z"
    }
  },
  "meta": {
    "current_page": 1,
    "total_pages": 10,
    "total_count": 100
  }
}

Error responses include detailed information:

{
  "error": {
    "message": "Validation failed",
    "details": {
      "field_name": ["error message"]
    }
  }
}

Need Help?

Support Resources

Community

  • Slack: Join our development community
  • Email: Contact support@saferide.org

Recent Updates

  • November 2025: Added comprehensive tutorial system
  • October 2025: AsyncAPI documentation for WebSocket APIs
  • October 2025: Dependabot automation for dependency management
  • September 2025: Enhanced location tracking and ride metrics