Skip to main content

​
Introduction

The Masar Eagle API is a RESTful API that provides access to all platform functionality for ride-hailing operations. The API is designed with a microservices architecture and uses a gateway pattern to route requests to the appropriate services.

​
Base URLs

All API requests are routed through the API Gateway: 
https://api.masareagle.com
The gateway routes requests to the following internal services:
  • Identity Service - Authentication and OTP management (http://identity:8080)
  • Users Service - User profiles, drivers, passengers, companies (http://user:8080)
  • Trips Service - Trip management, bookings, wallets (http://trip:8080)
  • Notifications Service - Push notifications and device management (http://notifications:8080)

​
API Architecture

The API uses YARP (Yet Another Reverse Proxy) to route requests based on path patterns:

​
Route Pattern Examples

POST /connect/token
POST /api/auth/send-otp
POST /api/auth/resend-otp

​
API Versioning

The API currently uses path-based versioning for specific endpoints:
  • v1: /api/v1/trips/* - Legacy trip endpoints (maintained for backward compatibility)
  • Unversioned: Most endpoints use unversioned paths as the current stable version
Future versions will be introduced with new path prefixes (e.g., /api/v2/) when breaking changes are necessary.
Unversioned endpoints represent the current stable API. Versioned endpoints (v1) are maintained for backward compatibility but may be deprecated in future releases.

​
Request Format

​
Content Types

The API accepts the following content types:
  • application/json - For most API requests
  • multipart/form-data - For file uploads (images, documents)
  • application/x-www-form-urlencoded - For OAuth token requests

​
Headers

​
Content-Type
string
required
The content type of the request body. Typically application/json.
​
Authorization
string
required
Bearer token for authenticated requests: Bearer {access_token}
​
Accept-Language
string
Preferred language for error messages. Supports ar (Arabic) and en (English). Default: ar

​
JSON Serialization

The API uses the following JSON conventions:
  • Property naming: camelCase (e.g., phoneNumber, userId)
  • Date/Time format: ISO 8601 UTC timestamps (e.g., 2024-03-10T14:30:00.000Z)
  • Enums: String values (e.g., "admin", "driver", "passenger")
  • Case insensitivity: Request property names are case-insensitive
{
  "phoneNumber": "+966501234567",
  "userType": "driver",
  "timestamp": "2024-03-10T14:30:00.000Z"
}

​
Response Format

​
Success Responses

Successful responses return the requested data with appropriate HTTP status codes: 
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "phoneNumber": "+966501234567",
  "userType": "driver",
  "createdAt": "2024-03-10T14:30:00.000Z"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeMeaningDescription
200OKRequest succeeded
201CreatedResource successfully created
204No ContentRequest succeeded with no response body
400Bad RequestInvalid request data or validation error
401UnauthorizedAuthentication required or invalid token
403ForbiddenInsufficient permissions
404Not FoundResource not found
409ConflictResource conflict (duplicate, etc.)
500Internal Server ErrorServer error
502Bad GatewayError connecting to backend service
504Gateway TimeoutRequest timeout

​
File Uploads

File upload endpoints support multipart/form-data with the following limits:

Max Request Size

Unlimited (configured via Kestrel)

Supported Formats

Images: JPEG, PNG, WebP, GIF

​
Upload Example

curl -X POST https://api.masareagle.com/api/drivers/me/profile-image \
  -H "Authorization: Bearer {access_token}" \
  -F "image=@/path/to/image.jpg"

​
Cross-Origin Resource Sharing (CORS)

The API supports CORS with the following configuration:
  • Allowed Origins: All origins (*)
  • Allowed Methods: All methods (GET, POST, PUT, PATCH, DELETE, etc.)
  • Allowed Headers: All headers
  • Credentials: Not supported (use Authorization header instead)
In production, CORS should be configured to allow only trusted origins for security.

​
Request/Response Logging

The gateway logs all requests and responses for monitoring and debugging:

​
Logged Information

  • Request path, method, and headers (excluding sensitive headers)
  • Response status code and headers
  • Request/response timestamps and duration
  • User ID and trace ID for correlation

​
Excluded from Logs

  • Authorization tokens
  • Cookies
  • API keys
  • Request/response bodies (configurable)
  • Health check endpoints (/health, /metrics, /ready, /live)

​
Performance Considerations

Response Times

Typical response times: 50-200msTimeouts: 30 seconds (configurable)

Request Limits

No global rate limits currently enforcedService-level limits may apply

​
OpenAPI/Swagger Documentation

Interactive API documentation is available for each service:
  • Identity Service: http://identity:8080/swagger
  • Users Service: http://user:8080/swagger
  • Trips Service: http://trip:8080/swagger
  • Notifications Service: http://notifications:8080/swagger
Swagger endpoints are typically available only in development environments.

​
Next Steps

Authentication

Learn how to authenticate and obtain access tokens

Error Handling

Understand error responses and how to handle them

Build docs developers (and LLMs) love

Get started for freeTalk to us