REST API Documentation

class MadadAPIClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.accessToken = null;
    this.refreshToken = null;
    this.retryCount = 0;
    this.maxRetries = 3;
  }

  async login(email, password) {
    const response = await fetch(`${this.baseUrl}/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password }),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    const data = await response.json();
    this.accessToken = data.access_token;
    this.refreshToken = data.refresh_token;
    return data;
  }

  async getProducts(pageSize = 25, pageToken = null) {
    const params = new URLSearchParams({ page_size: pageSize });
    if (pageToken) params.append('page_token', pageToken);

    return this.makeAuthenticatedRequest(`/products?${params}`);
  }

  async makeAuthenticatedRequest(endpoint, options = {}) {
    const headers = {
      'Authorization': `Bearer ${this.accessToken}`,
      'Content-Type': 'application/json',
      ...options.headers,
    };

    try {
      const response = await fetch(`${this.baseUrl}${endpoint}`, {
        ...options,
        headers,
      });

      // Handle rate limiting
      if (response.status === 429) {
        const errorData = await response.json();
        const retryAfter = errorData.retry_after || 60;
        
        if (this.retryCount < this.maxRetries) {
          this.retryCount++;
          console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
          await this.delay(retryAfter * 1000);
          return this.makeAuthenticatedRequest(endpoint, options);
        }
        throw new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
      }

      // Handle token expiration
      if (response.status === 401) {
        const errorData = await response.json();
        if (errorData.error === 'token_expired') {
          await this.refreshTokens();
          headers['Authorization'] = `Bearer ${this.accessToken}`;
          return fetch(`${this.baseUrl}${endpoint}`, { ...options, headers });
        }
      }

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message);
      }

      this.retryCount = 0; // Reset on success
      return response.json();
    } catch (error) {
      if (error.name === 'TypeError') {
        throw new Error('Network error. Please check your connection.');
      }
      throw error;
    }
  }

  async refreshTokens() {
    const response = await fetch(`${this.baseUrl}/refresh`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ refresh_token: this.refreshToken }),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    const data = await response.json();
    this.accessToken = data.access_token;
    this.refreshToken = data.refresh_token;
    return data;
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// Usage with error handling
const client = new MadadAPIClient('https://api.madad.app');

async function example() {
  try {
    await client.login('developer@example.com', 'password');
    const products = await client.getProducts(10);
    console.log('Products:', products);
  } catch (error) {
    if (error.message.includes('Rate limit')) {
      console.log('Rate limited - implement exponential backoff');
    } else {
      console.error('API Error:', error.message);
    }
  }
}

# 1. Health check (no auth required)
curl -X GET https://api.madad.app/health

# 2. Login (rate limited: 5 requests per 15 minutes)
curl -X POST https://api.madad.app/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "your-password"
  }'

# 3. Get products with rate limit headers (60 requests per minute)
curl -X GET "https://api.madad.app/products?page_size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -I  # Include headers to see rate limiting info

# 4. Handle rate limiting with retry
curl -X GET "https://api.madad.app/products" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --retry 3 \
  --retry-delay 60 \
  --retry-connrefused

# 5. Refresh token (rate limited: 5 requests per 15 minutes)
curl -X POST https://api.madad.app/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

# Example rate limit response (429):
# {
#   "error": "too_many_requests",
#   "message": "Too many requests from this IP, please try again in 15 minutes.",
#   "retry_after": 900
# }