mockapi/examples/README.md

# API Testing Collections for MockAPI

This directory contains ready-to-use API collections for testing the MockAPI application with OAuth2 provider.

## Available Collections

### 1. Bruno Collection (`mockapi-collection.bru`)
- **Format**: Bruno native format (`.bru`)
- **Features**: Scripting support, environment variables, folder organization
- **Import**: Drag and drop into Bruno or use "Import Collection"

### 2. Postman Collection (`mockapi-postman-collection.json`)
- **Format**: Postman Collection v2.1
- **Features**: Pre-request scripts, tests, environment variables
- **Import**: Import into Postman via "Import" button

### 3. Setup Scripts
- `setup-test-client.py`: Creates test OAuth client in database
- `setup.sh`: Interactive setup helper

## Collection Features

Both collections include:

### Global Variables
- `baseUrl`: Base URL of your MockAPI instance (default: `http://localhost:8000`)
- `adminUsername`, `adminPassword`: Admin credentials (default: `admin`/`admin123`)
- `clientId`, `clientSecret`: OAuth2 client credentials (use `test_client`/`test_secret` after setup)
- `accessToken`, `refreshToken`, `authCode`: OAuth2 tokens (auto-populated)
- `endpointId`: ID of created mock endpoints (auto-populated)

### Request Folders

1. **Health Check** - Basic health endpoint
2. **Admin - Login** - Admin authentication (sets session cookie)
3. **Mock Endpoints** - CRUD operations for mock endpoints
   - Create, list, update, delete endpoints
   - Call mock endpoints with template variables
4. **OAuth2** - Full OAuth2 flow testing
   - Client credentials grant
   - Authorization code grant (2-step)
   - Refresh token grant
   - Token introspection and revocation
   - OpenID Connect discovery
5. **Admin OAuth Management** - OAuth2 admin UI endpoints
6. **Protected Endpoint Example** - Create and test OAuth-protected endpoints

## Quick Setup

### 1. Start MockAPI Server
```bash
# Development (auto-reload)
python run.py

# Or production
waitress-serve --host=0.0.0.0 --port=8000 wsgi:wsgi_app
```

### 2. Create Test OAuth Client
```bash
# Run setup script
./examples/setup.sh

# Or directly
python examples/setup-test-client.py
```

This creates an OAuth client with:
- **Client ID**: `test_client`
- **Client Secret**: `test_secret`
- **Grant Types**: `authorization_code`, `client_credentials`, `refresh_token`
- **Scopes**: `openid`, `profile`, `email`, `api:read`, `api:write`

### 3. Import Collection
- **Bruno**: Import `mockapi-collection.bru`
- **Postman**: Import `mockapi-postman-collection.json`

### 4. Update Variables (if needed)
- Update `baseUrl` if server runs on different host/port
- Use `test_client`/`test_secret` for OAuth2 testing

## Testing Workflow

### Basic Testing
1. Run **Health Check** to verify server is running
2. Run **Admin - Login** to authenticate (sets session cookie)
3. Use **Mock Endpoints** folder to create and test endpoints

### OAuth2 Testing
1. Ensure test client is created (`test_client`/`test_secret`)
2. Run **Client Credentials Grant** to get access token
3. Token is automatically saved to `accessToken` variable
4. Use token in protected endpoint requests

### Protected Endpoints
1. Create protected endpoint using **Create OAuth-Protected Endpoint**
2. Test unauthorized access (should fail with 401/403)
3. Test authorized access with saved token

## Collection-Specific Features

### Bruno Features
- **Scripting**: JavaScript scripts for request/response handling
- **Variables**: `{{variable}}` syntax in URLs, headers, body
- **`btoa()` function**: Built-in for Basic auth encoding
- **Console logs**: Script output in Bruno console

### Postman Features
- **Pre-request scripts**: Setup before requests
- **Tests**: JavaScript tests after responses
- **Environment variables**: Separate from collection variables
- **Basic auth UI**: Built-in authentication helpers

## Manual Testing with cURL

For quick manual testing without collections:

```bash
# Health check
curl http://localhost:8000/health

# Create mock endpoint (after admin login)
curl -c cookies.txt -X POST http://localhost:8000/admin/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"

curl -b cookies.txt -X POST http://localhost:8000/admin/endpoints \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "route=/api/test&method=GET&response_body={\"message\":\"test\"}&response_code=200&content_type=application/json&is_active=true"

# OAuth2 client credentials grant
curl -X POST http://localhost:8000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=test_client&client_secret=test_secret&scope=api:read"
```

## Troubleshooting

### Common Issues

1. **401 Unauthorized (Admin endpoints)**
   - Run **Admin - Login** first
   - Check session cookies are being sent

2. **403 Forbidden (OAuth2)**
   - Verify token has required scopes
   - Check endpoint `oauth_scopes` configuration

3. **404 Not Found**
   - Endpoint may not be active (`is_active=true`)
   - Route may not be registered (refresh routes)

4. **Invalid OAuth Client**
   - Run setup script to create test client
   - Update `clientId`/`clientSecret` variables

5. **Bruno/Postman Import Errors**
   - Ensure JSON format is valid
   - Try re-downloading collection files

### Debug Tips

- Enable debug logging in MockAPI: Set `DEBUG=True` in `.env`
- Check Bruno/Postman console for script output
- Verify variables are set correctly before requests
- Test endpoints directly in browser: `http://localhost:8000/docs`

## Resources

- [MockAPI Documentation](../README.md)
- [Bruno Documentation](https://docs.usebruno.com/)
- [Postman Documentation](https://learning.postman.com/docs/getting-started/introduction/)
- [OAuth2 RFC 6749](https://tools.ietf.org/html/rfc6749)