Skip to content

API-Specification.md

Latest commit

 

History

History
234 lines (206 loc) · 7.27 KB

API-Specification.md

File metadata and controls

234 lines (206 loc) · 7.27 KB
Raw

Industrial Evidence Chain — REST API Specification

1. Overview & Base Configuration

The Industrial Evidence Chain Web API provides a RESTful interface for identity authentication, industrial asset querying, cryptographic evidence lifecycle operations, verification audits, and metrics aggregation.

  • Base URL: http://localhost:5000/api (or https://api.proofchain.local/api)
  • Protocol: HTTP/1.1 and HTTP/2 over TLS 1.3
  • Data Exchange Format: application/json (except multi-part media upload: multipart/form-data)
  • Security Scheme: Authorization: Bearer <JWT_TOKEN>

2. Authentication Endpoints (/api/auth)

2.1 User Login

  • Route: POST /api/auth/login
  • Anonymous: Allowed
  • Description: Authenticates user credentials and issues a signed HS256 JWT access token.
  • Request Body:
{
  "email": "tech@proofchain.local",
  "password": "Tech@123456"
}
  • Response 200 OK:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "tech@proofchain.local",
  "name": "Alex Rivera",
  "roles": ["Technician"],
  "expiresAt": "2026-09-05T12:00:00Z"
}
  • Error Codes: 400 Bad Request (Validation failure), 401 Unauthorized (Invalid credentials).

3. Asset Management Endpoints (/api/assets)

3.1 List Assets

  • Route: GET /api/assets
  • Roles: All authenticated roles
  • Query Parameters: search (string), category (string), status (string)
  • Response 200 OK:
[
  {
    "id": "11111111-1111-1111-1111-111111111111",
    "assetCode": "MACHINE-001",
    "name": "Siemens SGT-800 Gas Turbine",
    "category": "Turbine",
    "location": "Power Generation Bay 3",
    "status": "ACTIVE",
    "serialNumber": "SN-SGT800-9948",
    "evidenceCount": 12,
    "createdAt": "2026-01-15T08:00:00Z"
  }
]

3.2 Get Asset by ID

  • Route: GET /api/assets/{id}
  • Roles: All authenticated roles
  • Response 200 OK: Single asset detail object.

3.3 Get Asset by Unique Asset Code

  • Route: GET /api/assets/code/{code}
  • Roles: All authenticated roles
  • Description: Used by the QR scanner to resolve optical payload.

3.4 Get Asset Evidence History

  • Route: GET /api/assets/{id}/history
  • Roles: All authenticated roles
  • Description: Returns chronological inspection and maintenance events for the target equipment.

3.5 Generate Asset QR Code Image

  • Route: GET /api/assets/{id}/qr
  • Roles: All authenticated roles
  • Response 200 OK: image/png binary stream containing the machine-readable optical code.

3.6 Register New Asset

  • Route: POST /api/assets
  • Roles: Admin, Manager
  • Request Body:
{
  "assetCode": "COMPRESSOR-002",
  "name": "Atlas Copco GA-90 Compressor",
  "category": "Compressor",
  "location": "Utility Yard B",
  "serialNumber": "AC-GA90-2026"
}
  • Response 201 Created: Returns created asset object.

4. Evidence Management Endpoints (/api/evidence)

4.1 List Evidence Records

  • Route: GET /api/evidence
  • Roles: All authenticated roles
  • Query Parameters: assetId (UUID), status (DRAFT, SUBMITTED, ANCHORED), activityType (string)
  • Response 200 OK: Array of evidence summaries.

4.2 Get Evidence Details

  • Route: GET /api/evidence/{id}
  • Roles: All authenticated roles
  • Response 200 OK: Full evidence record including canonical hash, coordinate telemetry, media attachments, and blockchain proof.

4.3 Create Evidence Record

  • Route: POST /api/evidence
  • Roles: Technician, Admin
  • Request Body:
{
  "assetId": "11111111-1111-1111-1111-111111111111",
  "activityType": "INSPECTION",
  "description": "Routine vibration survey on turbine bearing housing.",
  "latitude": 18.520430,
  "longitude": 73.856744,
  "capturedAt": "2026-09-04T10:00:00Z"
}
  • Response 201 Created: Returns initialized evidence in DRAFT status.

4.4 Upload Evidence Media

  • Route: POST /api/evidence/{id}/upload
  • Roles: Technician, Admin
  • Content-Type: multipart/form-data
  • Form Data: file (binary stream, max 50MB)
  • Response 200 OK:
{
  "id": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fileName": "bearing_vibration_scan.jpg",
  "fileHash": "7d5a91b2e5647a829285496cfc3c840248c899c755fca78eefd2d09852f502d9",
  "fileSizeBytes": 451820,
  "mimeType": "image/jpeg"
}

4.5 Submit Evidence Record

  • Route: POST /api/evidence/{id}/submit
  • Roles: Technician, Manager, Admin
  • Description: Transitions record to SUBMITTED, normalizes JSON, and calculates the canonical SHA-256 evidence hash.
  • Response 200 OK:
{
  "id": "e47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "SUBMITTED",
  "evidenceHash": "5285fb70c383f23a9d9e6e8eebf82b8b9310bfbaae9ea2cf4b64f4ecf9ce152c",
  "updatedAt": "2026-09-04T10:05:00Z"
}

4.6 Anchor Evidence to Blockchain

  • Route: POST /api/evidence/{id}/anchor
  • Roles: Manager, Admin
  • Description: Commits canonical hash onto Hyperledger Fabric (or Local Ledger) and transitions status to ANCHORED.
  • Response 200 OK:
{
  "id": "99fa85f6-5717-4562-b3fc-2c963f66afa6",
  "evidenceId": "e47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transactionId": "tx-8b77a06f30a94488b394143419bb60b4",
  "blockNumber": 1048,
  "channelName": "evidence-channel",
  "proofStatus": "COMMITTED",
  "anchoredAt": "2026-09-04T10:06:12Z"
}

4.7 Verify Evidence Integrity

  • Route: GET /api/evidence/{id}/verify
  • Roles: All authenticated roles
  • Description: Recalculates current database SHA-256 hash and compares against the ledger anchor.
  • Response 200 OK (Valid):
{
  "evidenceId": "e47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "VERIFIED",
  "computedHash": "5285fb70c383f23a9d9e6e8eebf82b8b9310bfbaae9ea2cf4b64f4ecf9ce152c",
  "blockchainHash": "5285fb70c383f23a9d9e6e8eebf82b8b9310bfbaae9ea2cf4b64f4ecf9ce152c",
  "isTampered": false,
  "confidenceScore": 1.0,
  "transactionId": "tx-8b77a06f30a94488b394143419bb60b4",
  "blockNumber": 1048,
  "anchoredAt": "2026-09-04T10:06:12Z",
  "verifiedAt": "2026-09-04T10:15:00Z"
}

4.8 Tamper Simulation Endpoint

  • Route: POST /api/evidence/{id}/tamper
  • Roles: Admin
  • Description: Viva/evaluation utility that modifies database fields without updating the blockchain to demonstrate live tamper detection.
  • Request Body:
{
  "field": "description",
  "newValue": "UNAUTHORIZED TAMPERED TEXT: All turbine bearings wiped clean."
}
  • Response 200 OK: Returns updated record indicating tampering has been staged. Subsequent /verify will return INTEGRITY_MISMATCH.

5. Audit & Dashboard Endpoints

5.1 Query Audit Logs

  • Route: GET /api/audit-logs
  • Roles: Auditor, Admin
  • Query Parameters: action (string), userId (UUID), limit (int, default 50)
  • Response 200 OK: Chronological array of audit trail records.

5.2 System Metrics & Dashboard Statistics

  • Route: GET /api/dashboard/stats
  • Roles: All authenticated roles
  • Response 200 OK:
{
  "totalAssets": 5,
  "totalEvidence": 24,
  "anchoredEvidence": 19,
  "pendingEvidence": 5,
  "tamperedEvidenceCount": 0,
  "recentActivities": []
}