Initial commit
This commit is contained in:
defiQUG
234
docs/api/README.md
Normal file
234
docs/api/README.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user