smoa/docs/api/README.md

# SMOA API Documentation

**Version:** 1.0  
**Last Updated:** 2024-12-20  
**Status:** In Progress

---

## Overview

This directory contains API documentation for the Secure Mobile Operations Application (SMOA). The API documentation includes OpenAPI specifications, generated documentation, and API reference guides.

---

## API Specification

### OpenAPI Specification
- **File:** [api-specification.yaml](api-specification.yaml)
- **Format:** OpenAPI 3.0.3
- **Status:** In Progress

### Generated Documentation
- **Location:** [generated/](generated/)
- **Format:** HTML (generated from OpenAPI spec)
- **Status:** To be generated

---

## API Endpoints

### Authentication APIs
- `POST /auth/login` - Authenticate user
- `POST /auth/logout` - Logout user
- `POST /auth/refresh` - Refresh authentication token

### Credential APIs
- `GET /credentials` - List credentials
- `POST /credentials` - Create credential
- `GET /credentials/{id}` - Get credential by ID
- `PUT /credentials/{id}` - Update credential
- `DELETE /credentials/{id}` - Delete credential

### Order APIs
- `GET /orders` - List orders
- `POST /orders` - Create order
- `GET /orders/{id}` - Get order by ID
- `PUT /orders/{id}` - Update order
- `DELETE /orders/{id}` - Delete order

### Evidence APIs
- `GET /evidence` - List evidence items
- `POST /evidence` - Create evidence item
- `GET /evidence/{id}` - Get evidence by ID
- `POST /evidence/{id}/transfer` - Transfer custody

### Report APIs
- `POST /reports` - Generate report
- `GET /reports/templates` - List report templates
- `GET /reports/{id}` - Get report by ID

### Communication APIs
- `GET /communications/channels` - List communication channels
- `POST /communications/message` - Send message
- `GET /communications/messages` - List messages

### Directory APIs
- `GET /directory/contacts` - List contacts
- `GET /directory/search` - Search directory
- `GET /directory/{id}` - Get contact by ID

---

## Authentication

### Authentication Methods
- **Bearer Token:** JWT token in Authorization header
- **API Key:** API key in X-API-Key header

### Authentication Flow
1. User authenticates with PIN + Biometric
2. System returns JWT token
3. Client includes token in Authorization header
4. Token expires after configured time
5. Client refreshes token as needed

---

## Data Models

See [api-specification.yaml](api-specification.yaml) for complete data model definitions.

### Common Models
- **User:** User information
- **ErrorResponse:** Error response format
- **Pagination:** Pagination parameters and response

### Domain Models
- **Credential:** Digital credential
- **Order:** Order/authorization
- **Evidence:** Evidence item
- **Report:** Generated report
- **Message:** Communication message
- **Contact:** Directory contact

---

## Error Handling

### Error Response Format
```json
{
  "error": "Error code",
  "message": "Human-readable error message",
  "code": "ERROR_CODE",
  "timestamp": "2024-12-20T12:00:00Z"
}
```

### HTTP Status Codes
- **200 OK:** Request successful
- **201 Created:** Resource created
- **400 Bad Request:** Invalid request
- **401 Unauthorized:** Authentication required
- **403 Forbidden:** Access denied
- **404 Not Found:** Resource not found
- **429 Too Many Requests:** Rate limit exceeded
- **500 Internal Server Error:** Server error

---

## Rate Limiting

### Rate Limits
- **Authentication:** 5 requests per minute
- **General APIs:** 100 requests per minute
- **Report Generation:** 10 requests per minute

### Rate Limit Headers
- `X-RateLimit-Limit:` Maximum requests
- `X-RateLimit-Remaining:` Remaining requests
- `X-RateLimit-Reset:` Reset time (Unix timestamp)

---

## API Versioning

### Versioning Strategy
- URL-based versioning: `/v1/`, `/v2/`, etc.
- Current version: v1
- Backward compatibility maintained for at least 2 versions

---

## SDK Documentation

### Android SDK
- **Status:** To be created
- **Location:** TBD
- **Documentation:** TBD

---

## Examples

### Authentication Example
```kotlin
// Login request
val loginRequest = LoginRequest(
    pin = "123456",
    biometricToken = "biometric_token_here"
)

val response = apiService.login(loginRequest)
val token = response.token
```

### Get Credentials Example
```kotlin
// Get credentials
val credentials = apiService.getCredentials()
```

### Create Order Example
```kotlin
// Create order
val orderRequest = OrderCreate(
    type = "search_warrant",
    title = "Search Warrant #12345",
    content = "Order content here"
)

val order = apiService.createOrder(orderRequest)
```

---

## Testing

### Test Environment
- **Base URL:** https://api-dev.smoa.example.com/v1
- **Test Credentials:** See test documentation

### API Testing Tools
- Postman collection (to be created)
- cURL examples (to be created)
- Integration tests (to be created)

---

## Changelog

### Version 1.0.0 (2024-12-20)
- Initial API specification
- Authentication endpoints
- Credential endpoints
- Order endpoints
- Evidence endpoints
- Report endpoints

---

## References

- [OpenAPI Specification](api-specification.yaml)
- [Architecture Documentation](../architecture/ARCHITECTURE.md)
- [Implementation Status](../IMPLEMENTATION_STATUS.md)

---

**Document Owner:** API Lead  
**Last Updated:** 2024-12-20  
**Status:** In Progress  
**Next Review:** 2024-12-27