smoa/docs/api

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.

Android client map: How the in-app menu / navigation relates to /api/v1 pull and sync (and local caches) is documented in ../architecture/MENU-AND-ENDPOINTS.md (Mermaid diagram).

---

API Specification

OpenAPI Specification

• File: api-specification.yaml
• Format: OpenAPI 3.0.3
• Status: In Progress

Generated Documentation

• Location: generated/ (index.html + bundled spec copy)
• Format: HTML (ReDoc; regenerate with bash scripts/generate-api-docs.sh after editing api-specification.yaml)
• Status: Tracked in git

---

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 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

{
  "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

// Login request
val loginRequest = LoginRequest(
    pin = "123456",
    biometricToken = "biometric_token_here"
)

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

Get Credentials Example

// Get credentials
val credentials = apiService.getCredentials()

Create Order Example

// 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
• Architecture Documentation
• Implementation Status

---

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