# Postman Testing Guide

## Setup

1. **Start Laravel Server**
   ```bash
   cd face-platform
   php artisan serve
   ```
   Server will run on: `http://127.0.0.1:8000`

2. **Check Server is Running**
   - Open browser: `http://127.0.0.1:8000/up`
   - Should see: `{"status":"Healthy"}`

## Postman Collection

### 1. Create Client (Get API Key)

**Request:**
- Method: `POST`
- URL: `http://127.0.0.1:8000/api/admin/clients`
- Headers:
  ```
  Content-Type: application/json
  ```
- Body (raw JSON):
  ```json
  {
    "name": "Acme Corporation"
  }
  ```

**Expected Response (201):**
```json
{
  "message": "Client created successfully",
  "data": {
    "id": 1,
    "name": "Acme Corporation",
    "api_key": "face_T3j4R8eO73bvwGfCnxGUQvIo9biRzeWK7aV8QmRx",
    "is_active": true,
    "created_at": "2026-02-07T10:00:00.000000Z",
    "updated_at": "2026-02-07T10:00:00.000000Z"
  }
}
```

**⚠️ IMPORTANT:** Copy the `api_key` value - you'll need it for the next requests!

---

### 2. Register Face

**Request:**
- Method: `POST`
- URL: `http://127.0.0.1:8000/api/face/register`
- Headers:
  ```
  Content-Type: application/json
  X-API-KEY: face_T3j4R8eO73bvwGfCnxGUQvIo9biRzeWK7aV8QmRx
  ```
  (Replace with your actual API key from step 1)
  
- Body (raw JSON):
  ```json
  {
    "reference_id": "user_12345",
    "image": "base64_encoded_image_here"
  }
  ```

**Expected Response (from Python service):**
```json
{
  "success": true,
  "reference_id": "user_12345",
  "message": "Face registered successfully"
}
```

---

### 3. Verify Face

**Request:**
- Method: `POST`
- URL: `http://127.0.0.1:8000/api/face/verify`
- Headers:
  ```
  Content-Type: application/json
  X-API-KEY: face_T3j4R8eO73bvwGfCnxGUQvIo9biRzeWK7aV8QmRx
  ```
- Body (raw JSON):
  ```json
  {
    "reference_id": "user_12345",
    "image": "base64_encoded_image_here"
  }
  ```

**Expected Response (from Python service):**
```json
{
  "success": true,
  "match": true,
  "confidence": 0.95,
  "reference_id": "user_12345"
}
```

---

### 4. List All Clients

**Request:**
- Method: `GET`
- URL: `http://127.0.0.1:8000/api/admin/clients`
- Headers: None needed

**Expected Response (200):**
```json
{
  "data": [
    {
      "id": 1,
      "name": "Acme Corporation",
      "is_active": true,
      "created_at": "2026-02-07T10:00:00.000000Z",
      "updated_at": "2026-02-07T10:00:00.000000Z"
    }
  ]
}
```

---

### 5. Deactivate Client

**Request:**
- Method: `PATCH`
- URL: `http://127.0.0.1:8000/api/admin/clients/1/status`
- Headers:
  ```
  Content-Type: application/json
  ```
- Body (raw JSON):
  ```json
  {
    "is_active": false
  }
  ```

**Expected Response (200):**
```json
{
  "message": "Client status updated",
  "data": {
    "id": 1,
    "name": "Acme Corporation",
    "is_active": false,
    "created_at": "2026-02-07T10:00:00.000000Z",
    "updated_at": "2026-02-07T10:00:00.000000Z"
  }
}
```

---

## Error Testing

### Test 1: Missing API Key
- Method: `POST`
- URL: `http://127.0.0.1:8000/api/face/register`
- Headers: `Content-Type: application/json` (NO X-API-KEY)
- Body: `{"reference_id":"user_123","image":"data"}`

**Expected: 401**
```json
{
  "error": "API key required"
}
```

### Test 2: Invalid API Key
- Method: `POST`
- URL: `http://127.0.0.1:8000/api/face/register`
- Headers:
  ```
  Content-Type: application/json
  X-API-KEY: invalid_key_12345
  ```
- Body: `{"reference_id":"user_123","image":"data"}`

**Expected: 401**
```json
{
  "error": "Invalid API key"
}
```

### Test 3: Missing Required Field
- Method: `POST`
- URL: `http://127.0.0.1:8000/api/face/register`
- Headers:
  ```
  Content-Type: application/json
  X-API-KEY: face_xxx (your valid key)
  ```
- Body: `{"reference_id":"user_123"}` (missing image)

**Expected: 422**
```json
{
  "message": "The image field is required.",
  "errors": {
    "image": ["The image field is required."]
  }
}
```

---

## Quick Setup in Postman

### Using Environment Variables

1. Create new Environment: "Face Platform"
2. Add variables:
   - `base_url`: `http://127.0.0.1:8000`
   - `api_key`: (leave empty, will fill after creating client)

3. Update URLs to use: `{{base_url}}/api/admin/clients`
4. After creating client, copy API key to environment variable
5. Use `{{api_key}}` in X-API-KEY header

### Collection Structure
```
Face Platform API
├── Admin
│   ├── Create Client
│   ├── List Clients
│   └── Update Client Status
└── Face API
    ├── Register Face
    └── Verify Face
```

---

## Troubleshooting

### Server Not Running
**Error:** "Could not get any response"
**Solution:** 
```bash
cd face-platform
php artisan serve
```

### Port Already in Use
**Error:** "Address already in use"
**Solution:**
```bash
php artisan serve --port=8080
```
Then use: `http://127.0.0.1:8080` in Postman

### Database Connection Error
**Solution:**
```bash
# Check MAMP is running
# Verify .env settings:
DB_HOST=127.0.0.1
DB_PORT=8889
DB_DATABASE=face_platform
DB_USERNAME=root
DB_PASSWORD=root
```

---

## Testing Checklist

- [ ] Server is running (`php artisan serve`)
- [ ] Health check works (`/up`)
- [ ] Create client returns API key
- [ ] Register face with valid API key
- [ ] Verify face with valid API key
- [ ] List clients works
- [ ] Deactivate client works
- [ ] Revoked API key returns 401
- [ ] Missing API key returns 401
- [ ] Invalid API key returns 401
- [ ] Missing fields return 422