Enhance documentation across multiple files by adding standardized document metadata, including versioning, effective dates, and classification. Introduce comprehensive tables of contents and detailed sections for improved navigation and clarity. Update the Master Index to reflect the total document count and status summary, ensuring consistency and compliance with established standards.
This commit is contained in:
defiQUG
376
gru_reserve_system/appendices/Appendix_B_API_Specifications.md
Normal file
376
gru_reserve_system/appendices/Appendix_B_API_Specifications.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# APPENDIX B: API SPECIFICATIONS
|
||||
## Complete API Documentation for GRU Reserve System
|
||||
|
||||
**Document Number:** DBIS-GRU-APP-B
|
||||
**Version:** 1.0
|
||||
**Date:** [Enter date in ISO 8601 format: YYYY-MM-DD]
|
||||
**Classification:** CONFIDENTIAL
|
||||
**Authority:** DBIS Technical Department
|
||||
|
||||
---
|
||||
|
||||
## PREAMBLE
|
||||
|
||||
This appendix provides complete API specifications for the GRU Reserve System, including REST API endpoints, request/response formats, authentication, and error handling.
|
||||
|
||||
---
|
||||
|
||||
## PART I: API OVERVIEW
|
||||
|
||||
### Section 1.1: API Architecture
|
||||
|
||||
**API Type:** RESTful API
|
||||
|
||||
**Base URL:** `https://api.dbis.org/v1/reserve`
|
||||
|
||||
**API Versioning:**
|
||||
- Current version: v1
|
||||
- Version specified in URL path
|
||||
- Backward compatibility maintained for at least 2 versions
|
||||
|
||||
**Authentication:**
|
||||
- OAuth 2.0 with JWT tokens
|
||||
- API keys for service-to-service communication
|
||||
- Certificate-based authentication for high-security operations
|
||||
|
||||
---
|
||||
|
||||
## PART II: RESERVE MANAGEMENT APIs
|
||||
|
||||
### Section 2.1: Get Reserve Status
|
||||
|
||||
**Endpoint:** `GET /reserve/status`
|
||||
|
||||
**Authentication:** Required (API key or OAuth token)
|
||||
|
||||
**Request:**
|
||||
```
|
||||
GET /v1/reserve/status
|
||||
Headers:
|
||||
Authorization: Bearer {token}
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"total_reserves": 34500000.00,
|
||||
"currency": "USD",
|
||||
"reserve_ratio": 1.15,
|
||||
"minimum_required": 30000000.00,
|
||||
"assets": [
|
||||
{
|
||||
"type": "XAU",
|
||||
"quantity": 10000.0,
|
||||
"unit": "oz",
|
||||
"value": 20000000.00,
|
||||
"weight": 1.0
|
||||
},
|
||||
{
|
||||
"type": "BTC",
|
||||
"quantity": 100.0,
|
||||
"unit": "BTC",
|
||||
"value": 5000000.00,
|
||||
"weight": 0.9
|
||||
}
|
||||
],
|
||||
"liabilities": {
|
||||
"total": 30000000.00,
|
||||
"currency": "USD"
|
||||
},
|
||||
"timestamp": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- 401 Unauthorized: Invalid or missing authentication
|
||||
- 403 Forbidden: Insufficient permissions
|
||||
- 500 Internal Server Error: Server error
|
||||
|
||||
---
|
||||
|
||||
### Section 2.2: Get Asset Details
|
||||
|
||||
**Endpoint:** `GET /reserve/assets/{asset_type}`
|
||||
|
||||
**Parameters:**
|
||||
- `asset_type`: Asset type (XAU, BTC, ETH, etc.)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"asset_type": "XAU",
|
||||
"quantity": 10000.0,
|
||||
"unit": "oz",
|
||||
"current_price": 2000.00,
|
||||
"value": 20000000.00,
|
||||
"location": "allocated",
|
||||
"purity": 0.9999,
|
||||
"last_updated": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PART III: CONVERSION APIs
|
||||
|
||||
### Section 3.1: Request Conversion
|
||||
|
||||
**Endpoint:** `POST /reserve/convert`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"source_asset": "USD",
|
||||
"target_asset": "XAU",
|
||||
"amount": 100000.00,
|
||||
"source_unit": "USD",
|
||||
"target_unit": "oz"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"conversion_id": "CONV-2024-001-12345",
|
||||
"source_asset": "USD",
|
||||
"target_asset": "XAU",
|
||||
"source_amount": 100000.00,
|
||||
"target_amount": 50.0,
|
||||
"conversion_rate": 2000.00,
|
||||
"fees": {
|
||||
"base_fee": 0.1,
|
||||
"slippage_fee": 0.0,
|
||||
"large_transaction_fee": 0.05,
|
||||
"total_fee": 0.15,
|
||||
"fee_amount": 0.075
|
||||
},
|
||||
"path": "direct",
|
||||
"estimated_settlement": "2024-01-15T10:35:00Z",
|
||||
"status": "pending"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
- 400 Bad Request: Invalid request parameters
|
||||
- 402 Payment Required: Insufficient reserves
|
||||
- 429 Too Many Requests: Rate limit exceeded
|
||||
|
||||
---
|
||||
|
||||
### Section 3.2: Get Conversion Status
|
||||
|
||||
**Endpoint:** `GET /reserve/convert/{conversion_id}`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"conversion_id": "CONV-2024-001-12345",
|
||||
"status": "completed",
|
||||
"source_asset": "USD",
|
||||
"target_asset": "XAU",
|
||||
"source_amount": 100000.00,
|
||||
"target_amount": 50.0,
|
||||
"actual_rate": 2000.00,
|
||||
"fees": {
|
||||
"total_fee": 0.15,
|
||||
"fee_amount": 0.075
|
||||
},
|
||||
"settled_at": "2024-01-15T10:35:00Z",
|
||||
"transaction_hash": "0x1234..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PART IV: BOND SYSTEM APIs
|
||||
|
||||
### Section 4.1: Issue Bonds
|
||||
|
||||
**Endpoint:** `POST /reserve/bonds/issue`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"amount": 1000000.00,
|
||||
"currency": "USD",
|
||||
"maturity_years": 5,
|
||||
"interest_rate": 0.03,
|
||||
"backing_assets": ["XAU"]
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"bond_id": "BOND-2024-001",
|
||||
"face_value": 1000000.00,
|
||||
"currency": "USD",
|
||||
"maturity_date": "2029-01-15",
|
||||
"interest_rate": 0.03,
|
||||
"issue_date": "2024-01-15",
|
||||
"backing_assets": ["XAU"],
|
||||
"backing_value": 1250000.00,
|
||||
"coverage_ratio": 1.25
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Section 4.2: Redeem Bonds
|
||||
|
||||
**Endpoint:** `POST /reserve/bonds/{bond_id}/redeem`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"redemption_amount": 1000000.00,
|
||||
"redemption_date": "2024-01-15"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"bond_id": "BOND-2024-001",
|
||||
"redemption_amount": 1000000.00,
|
||||
"accrued_interest": 25000.00,
|
||||
"total_redemption": 1025000.00,
|
||||
"redemption_date": "2024-01-15",
|
||||
"settlement_assets": ["XAU"],
|
||||
"settlement_amount": 512.5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PART V: AUTHENTICATION AND SECURITY
|
||||
|
||||
### Section 5.1: Authentication
|
||||
|
||||
**OAuth 2.0 Flow:**
|
||||
1. Client requests authorization
|
||||
2. User authorizes
|
||||
3. Authorization server issues access token
|
||||
4. Client uses access token for API requests
|
||||
5. Token refresh as needed
|
||||
|
||||
**API Key Authentication:**
|
||||
- API keys issued by DBIS
|
||||
- Keys rotated every 90 days
|
||||
- Keys stored securely (never in code)
|
||||
|
||||
**Certificate Authentication:**
|
||||
- X.509 certificates for high-security operations
|
||||
- Certificate validation required
|
||||
- Mutual TLS (mTLS) for certificate-based authentication
|
||||
|
||||
---
|
||||
|
||||
### Section 5.2: Rate Limiting
|
||||
|
||||
**Rate Limits:**
|
||||
- Standard API key: 100 requests per minute
|
||||
- OAuth token: 1000 requests per minute
|
||||
- Certificate-based: 10000 requests per minute
|
||||
|
||||
**Rate Limit Headers:**
|
||||
```
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 95
|
||||
X-RateLimit-Reset: 1642248000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PART VI: ERROR HANDLING
|
||||
|
||||
### Section 6.1: Error Response Format
|
||||
|
||||
**Standard Error Response:**
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"error": {
|
||||
"code": "RESERVE_INSUFFICIENT",
|
||||
"message": "Insufficient reserves for requested conversion",
|
||||
"details": {
|
||||
"required": 100000.00,
|
||||
"available": 50000.00
|
||||
},
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"request_id": "REQ-2024-001-12345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Codes:**
|
||||
- `AUTH_REQUIRED`: Authentication required
|
||||
- `AUTH_INVALID`: Invalid authentication
|
||||
- `PERMISSION_DENIED`: Insufficient permissions
|
||||
- `INVALID_REQUEST`: Invalid request parameters
|
||||
- `RESERVE_INSUFFICIENT`: Insufficient reserves
|
||||
- `CONVERSION_FAILED`: Conversion failed
|
||||
- `RATE_LIMIT_EXCEEDED`: Rate limit exceeded
|
||||
- `SERVER_ERROR`: Internal server error
|
||||
|
||||
---
|
||||
|
||||
## PART VII: WEBHOOKS AND NOTIFICATIONS
|
||||
|
||||
### Section 7.1: Webhook Events
|
||||
|
||||
**Event Types:**
|
||||
- `conversion.completed`: Conversion completed
|
||||
- `conversion.failed`: Conversion failed
|
||||
- `bond.issued`: Bond issued
|
||||
- `bond.redeemed`: Bond redeemed
|
||||
- `reserve.threshold`: Reserve threshold reached
|
||||
|
||||
**Webhook Payload:**
|
||||
```json
|
||||
{
|
||||
"event": "conversion.completed",
|
||||
"timestamp": "2024-01-15T10:35:00Z",
|
||||
"data": {
|
||||
"conversion_id": "CONV-2024-001-12345",
|
||||
"status": "completed"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## IMPLEMENTATION NOTES
|
||||
|
||||
- All APIs use HTTPS only (TLS 1.3)
|
||||
- All requests and responses are JSON
|
||||
- All timestamps in ISO 8601 format
|
||||
- All monetary amounts in base currency (USD) unless specified
|
||||
- API versioning in URL path
|
||||
- Comprehensive error handling
|
||||
- Rate limiting implemented
|
||||
- Audit logging for all API calls
|
||||
|
||||
---
|
||||
|
||||
**END OF APPENDIX B**
|
||||
|
||||
Reference in New Issue
Block a user