Skip to content

API.md

Latest commit

 

History

History
302 lines (217 loc) · 7.68 KB

API.md

File metadata and controls

302 lines (217 loc) · 7.68 KB

API Configuration Guide

This guide explains how to configure the mobile app to connect to your backend API, especially when you've moved the mobile folder to a new location or want to connect to a different backend server.

Quick Start

The mobile app needs to know where your backend API is running. By default, it's configured for local development, but you'll need to update this when:

  • Moving the mobile folder to a standalone project
  • Deploying to a remote server
  • Testing on a physical device
  • Connecting to a different backend environment

Configuration File

The API endpoint is configured in: src/services/api.ts

Step-by-Step Configuration

1. Locate the API Configuration

Open src/services/api.ts and find this line near the top:

const API_URL = 'http://10.0.2.2:3000';

2. Update the API_URL Based on Your Setup

Replace the API_URL value based on your scenario:

Scenario A: Local Development (Backend on Same Machine)

For Android Emulator:

const API_URL = 'http://10.0.2.2:3000';

10.0.2.2 is the special IP that Android emulator uses to access the host machine's localhost

For iOS Simulator:

const API_URL = 'http://localhost:3000';

For Physical Device on Same Network:

const API_URL = 'http://192.168.1.100:3000';

Replace 192.168.1.100 with your computer's actual IP address on your local network

Scenario B: Remote Backend Server

Production/Staging Server:

const API_URL = 'https://api.yourdomain.com';

Use HTTPS in production for security

Development Server:

const API_URL = 'http://dev.yourdomain.com:3000';

Scenario C: Multiple Environments

For better environment management, you can use environment variables:

const API_URL = __DEV__ 
  ? 'http://10.0.2.2:3000'  // Development
  : 'https://api.yourdomain.com';  // Production

3. Find Your Computer's IP Address

If testing on a physical device connected to the same WiFi:

Windows:

ipconfig

Look for "IPv4 Address" under your active network adapter (usually starts with 192.168.x.x or 10.0.x.x)

Mac/Linux:

ifconfig | grep "inet "

or

ip addr show

Quick Method (Any OS):

  • Windows: Settings → Network & Internet → WiFi → Properties
  • Mac: System Preferences → Network → Select WiFi → IP Address

4. Verify Backend is Accessible

Before testing the mobile app, ensure your backend:

  1. Is running - Start your backend server

  2. Allows connections - Check firewall settings

  3. Listens on the correct interface:

    • For physical devices: Backend must listen on 0.0.0.0 (all interfaces), not just localhost
    • Check your backend's main file (e.g., src/main.ts in NestJS): 
      await app.listen(3000, '0.0.0.0');

  4. Has CORS enabled - Your backend must allow requests from the mobile app

5. Test the Connection

After updating the API_URL:

  1. Restart the Metro bundler:

    npm start -- --reset-cache

  2. Rebuild the app:

    # Android
npm run android

# iOS
npm run ios

  3. Test login/registration to verify the connection works

Common Configuration Examples

Example 1: Standalone Mobile Project with Local Backend

You moved the mobile folder to ~/Projects/my-mobile-app/:

// src/services/api.ts
const API_URL = 'http://10.0.2.2:3000';  // Android
// OR
const API_URL = 'http://localhost:3000';  // iOS

Backend must be running on port 3000 on your computer.

Example 2: Mobile App with Remote Backend

Your backend is hosted at api.myapp.com:

// src/services/api.ts
const API_URL = 'https://api.myapp.com';

No port needed if using standard HTTPS (443).

Example 3: Testing on Physical Device

Your computer's local IP is 192.168.1.50, backend runs on port 3000:

// src/services/api.ts
const API_URL = 'http://192.168.1.50:3000';

Example 4: Advanced Multi-Environment Setup

Create a config file src/config/api.config.ts:

const ENV = {
  development: {
    apiUrl: __DEV__ ? 'http://10.0.2.2:3000' : 'http://localhost:3000',
  },
  staging: {
    apiUrl: 'https://staging-api.myapp.com',
  },
  production: {
    apiUrl: 'https://api.myapp.com',
  },
};

export const API_CONFIG = ENV.development; // Change based on environment

Then in src/services/api.ts:

import { API_CONFIG } from '../config/api.config';

const API_URL = API_CONFIG.apiUrl;

Troubleshooting

"Network request failed" Error

Cause: Mobile app can't reach the backend

Solutions:

  1. Verify backend is running: curl http://localhost:3000 or visit in browser
  2. Check firewall isn't blocking the port
  3. For physical devices: Ensure mobile and computer are on same WiFi
  4. For Android emulator: Use 10.0.2.2 instead of localhost
  5. Check the API_URL is correct in api.ts

"CORS Error"

Cause: Backend not allowing requests from mobile app

Solution: Update backend CORS configuration:

// In your backend (e.g., NestJS main.ts)
app.enableCors({
  origin: '*', // Or specify your mobile app's origin
  credentials: true,
});

Connection Works in Simulator but Not on Physical Device

Cause: Physical device can't access localhost

Solution:

  1. Find your computer's IP address (see Step 3 above)
  2. Update API_URL to use your IP: http://192.168.1.X:3000
  3. Ensure backend listens on 0.0.0.0, not just 127.0.0.1

"Unable to resolve host"

Cause: Invalid URL or DNS issue

Solutions:

  1. Check for typos in API_URL
  2. Verify domain exists if using remote server
  3. Try using IP address instead of domain name
  4. Check internet connection on device

Security Best Practices

Development

  • Use HTTP for local development
  • Use 10.0.2.2 or localhost for emulators/simulators

Production

  • Always use HTTPS for production APIs
  • Never hardcode sensitive credentials in the app
  • Use environment variables for API keys
  • Implement certificate pinning for additional security
  • Use secure token storage (already implemented with AsyncStorage)

Additional Notes

Port Numbers

  • Default backend port in this project: 3000
  • If your backend uses a different port, update accordingly: http://your-ip:YOUR_PORT

API Endpoints

The mobile app uses these main endpoint prefixes:

  • /auth/* - Authentication (login, register, verify email, etc.)
  • /events/* - Event management
  • /users/* - User settings

All endpoints are relative to the API_URL base.

Testing Multiple Backends

To quickly switch between backends during development, you can create a simple switcher:

// src/services/api.ts
const BACKENDS = {
  local: 'http://10.0.2.2:3000',
  staging: 'https://staging-api.myapp.com',
  production: 'https://api.myapp.com',
};

const API_URL = BACKENDS.local; // Change this to switch backends

Need Help?

If you're still having connection issues:

  1. Check backend logs for incoming requests
  2. Use a tool like Postman to verify backend endpoints work
  3. Enable network debugging in React Native Debugger
  4. Check Metro bundler terminal for error messages
  5. Verify your backend's CORS and firewall settings

Summary Checklist

When moving the mobile folder or connecting to a new backend:

  • Update API_URL in src/services/api.ts
  • Ensure backend is running and accessible
  • Configure backend to listen on 0.0.0.0 (for physical devices)
  • Enable CORS on backend
  • Use correct URL format (http/https, IP/domain, port)
  • Restart Metro bundler with cache clear
  • Rebuild the mobile app
  • Test login/registration functionality