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
|
||||
|
||||
469
docs/api/api-specification.yaml
Normal file
469
docs/api/api-specification.yaml
Normal file
@@ -0,0 +1,469 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: SMOA API Specification
|
||||
description: |
|
||||
API specification for Secure Mobile Operations Application (SMOA).
|
||||
This specification documents all internal and external APIs.
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: SMOA Development Team
|
||||
email: smoa-dev@example.com
|
||||
license:
|
||||
name: Proprietary - Government Use Only
|
||||
|
||||
servers:
|
||||
- url: https://api.smoa.example.com/v1
|
||||
description: Production server
|
||||
- url: https://api-dev.smoa.example.com/v1
|
||||
description: Development server
|
||||
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: Authentication and authorization endpoints
|
||||
- name: Credentials
|
||||
description: Digital credential management
|
||||
- name: Orders
|
||||
description: Orders management
|
||||
- name: Evidence
|
||||
description: Evidence chain of custody
|
||||
- name: Reports
|
||||
description: Report generation
|
||||
- name: Communications
|
||||
description: Secure communications
|
||||
- name: Directory
|
||||
description: Internal directory
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
- ApiKeyAuth: []
|
||||
|
||||
paths:
|
||||
/auth/login:
|
||||
post:
|
||||
tags:
|
||||
- Authentication
|
||||
summary: Authenticate user
|
||||
description: |
|
||||
Authenticate user with multi-factor authentication (PIN + Biometric).
|
||||
Returns authentication token on success.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Authentication successful
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginResponse'
|
||||
'401':
|
||||
description: Authentication failed
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'429':
|
||||
description: Too many login attempts
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/logout:
|
||||
post:
|
||||
tags:
|
||||
- Authentication
|
||||
summary: Logout user
|
||||
description: Invalidates current session
|
||||
responses:
|
||||
'200':
|
||||
description: Logout successful
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
/credentials:
|
||||
get:
|
||||
tags:
|
||||
- Credentials
|
||||
summary: List user credentials
|
||||
description: Returns list of credentials available to the authenticated user
|
||||
parameters:
|
||||
- name: type
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum: [id, badge, license, permit, other]
|
||||
description: Filter by credential type
|
||||
responses:
|
||||
'200':
|
||||
description: List of credentials
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Credential'
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
post:
|
||||
tags:
|
||||
- Credentials
|
||||
summary: Create new credential
|
||||
description: Creates a new digital credential
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CredentialCreate'
|
||||
responses:
|
||||
'201':
|
||||
description: Credential created
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Credential'
|
||||
'400':
|
||||
description: Invalid request
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
/credentials/{id}:
|
||||
get:
|
||||
tags:
|
||||
- Credentials
|
||||
summary: Get credential by ID
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: Credential ID
|
||||
responses:
|
||||
'200':
|
||||
description: Credential details
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Credential'
|
||||
'404':
|
||||
description: Credential not found
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
/orders:
|
||||
get:
|
||||
tags:
|
||||
- Orders
|
||||
summary: List orders
|
||||
description: Returns list of orders available to the authenticated user
|
||||
parameters:
|
||||
- name: status
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum: [draft, pending_approval, approved, issued, executed, expired, revoked]
|
||||
description: Filter by order status
|
||||
- name: type
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum: [authorization, assignment, search_warrant, arrest_warrant, court_order, administrative]
|
||||
description: Filter by order type
|
||||
responses:
|
||||
'200':
|
||||
description: List of orders
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Order'
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
post:
|
||||
tags:
|
||||
- Orders
|
||||
summary: Create new order
|
||||
description: Creates a new order
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OrderCreate'
|
||||
responses:
|
||||
'201':
|
||||
description: Order created
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Order'
|
||||
'400':
|
||||
description: Invalid request
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
/orders/{id}:
|
||||
get:
|
||||
tags:
|
||||
- Orders
|
||||
summary: Get order by ID
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: Order ID
|
||||
responses:
|
||||
'200':
|
||||
description: Order details
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Order'
|
||||
'404':
|
||||
description: Order not found
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
/evidence:
|
||||
get:
|
||||
tags:
|
||||
- Evidence
|
||||
summary: List evidence items
|
||||
description: Returns list of evidence items
|
||||
responses:
|
||||
'200':
|
||||
description: List of evidence items
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Evidence'
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
/reports:
|
||||
post:
|
||||
tags:
|
||||
- Reports
|
||||
summary: Generate report
|
||||
description: Generates a report in the specified format
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ReportRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Report generated
|
||||
content:
|
||||
application/pdf:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
application/json:
|
||||
schema:
|
||||
type: string
|
||||
application/xml:
|
||||
schema:
|
||||
type: string
|
||||
text/csv:
|
||||
schema:
|
||||
type: string
|
||||
'400':
|
||||
description: Invalid request
|
||||
'401':
|
||||
description: Unauthorized
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
ApiKeyAuth:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: X-API-Key
|
||||
|
||||
schemas:
|
||||
LoginRequest:
|
||||
type: object
|
||||
required:
|
||||
- pin
|
||||
- biometricToken
|
||||
properties:
|
||||
pin:
|
||||
type: string
|
||||
description: User PIN
|
||||
minLength: 6
|
||||
maxLength: 12
|
||||
biometricToken:
|
||||
type: string
|
||||
description: Biometric authentication token
|
||||
|
||||
LoginResponse:
|
||||
type: object
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: Authentication token
|
||||
expiresIn:
|
||||
type: integer
|
||||
description: Token expiration time in seconds
|
||||
user:
|
||||
$ref: '#/components/schemas/User'
|
||||
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
username:
|
||||
type: string
|
||||
roles:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
|
||||
Credential:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [id, badge, license, permit, other]
|
||||
title:
|
||||
type: string
|
||||
issuer:
|
||||
type: string
|
||||
issueDate:
|
||||
type: string
|
||||
format: date
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date
|
||||
status:
|
||||
type: string
|
||||
enum: [active, expired, revoked]
|
||||
barcode:
|
||||
type: string
|
||||
description: PDF417 barcode data
|
||||
|
||||
CredentialCreate:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- title
|
||||
- issuer
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
title:
|
||||
type: string
|
||||
issuer:
|
||||
type: string
|
||||
issueDate:
|
||||
type: string
|
||||
format: date
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date
|
||||
|
||||
Order:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [authorization, assignment, search_warrant, arrest_warrant, court_order, administrative]
|
||||
title:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
enum: [draft, pending_approval, approved, issued, executed, expired, revoked]
|
||||
issuedBy:
|
||||
type: string
|
||||
issueDate:
|
||||
type: string
|
||||
format: date-time
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
OrderCreate:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- title
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
title:
|
||||
type: string
|
||||
content:
|
||||
type: string
|
||||
expirationDate:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
Evidence:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
caseNumber:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [physical, digital, biological, chemical, firearm, document]
|
||||
collectionDate:
|
||||
type: string
|
||||
format: date-time
|
||||
currentCustodian:
|
||||
type: string
|
||||
|
||||
ReportRequest:
|
||||
type: object
|
||||
required:
|
||||
- template
|
||||
- format
|
||||
properties:
|
||||
template:
|
||||
type: string
|
||||
description: Report template name
|
||||
format:
|
||||
type: string
|
||||
enum: [pdf, xml, json, csv]
|
||||
parameters:
|
||||
type: object
|
||||
description: Template parameters
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
message:
|
||||
type: string
|
||||
code:
|
||||
type: string
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
Reference in New Issue
Block a user