Production-Ready
API Documentation
Healthcare JSON Prediction Service
From Data Validation to Clinical Integration
Stella Oiro
Technical Writer | Software Engineer | AWS Community Builder
Introduction & Project Overview
The Challenge
Sepsis kills over 270,000 people annually in the United States alone. Early detection can reduce mortality by up to 50%, but identifying at-risk patients requires continuous monitoring of multiple vital signs and rapid clinical response.
The Solution
A production-ready FastAPI service that analyzes patient vital signs and laboratory data to predict sepsis risk in real-time with 87% accuracy and <200ms response time.
My Role: Documentation Architect
As the technical writer and documentation architect for this project, I designed and implemented the complete API documentation strategy. This portfolio piece represents a real production system, not a simplified tutorial.
- Designed API documentation structure and information architecture
- Created comprehensive endpoint specifications with production-ready examples
- Developed JSON schema documentation and validation guides
- Designed error handling framework and error code taxonomy
API Reference Example
POST /api/v1/predict/sepsis
Real-time sepsis risk assessment
X-API-Key: your_api_key{
"patient_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2025-02-12T14:30:00Z",
"vital_signs": {
"heart_rate": 105,
"blood_pressure_systolic": 118,
"blood_pressure_diastolic": 76,
"temperature": 38.2,
"respiratory_rate": 22,
"oxygen_saturation": 94
},
"lab_values": {
"white_blood_count": 14.5,
"lactate": 2.8,
"creatinine": 1.2
}
}Production-Quality Examples
Four real clinical scenarios demonstrating API across different risk levels
Low Risk
Postoperative Day 2, vitals stable
Result: 12% probability | Routine monitoring
Moderate Risk
Emergency dept, suspected infection
Result: 67% probability | Increased vigilance
High Risk
ICU patient, deteriorating
Result: 85% probability | Immediate review
Critical Risk
Septic shock, multi-organ
Result: 96% probability | Emergency response
Why Real Scenarios Matter
Not "heart_rate: 100" but "Emergency dept admission with suspected infection" → Clinical context + realistic values = examples developers trust and clinical teams recognize.
Documentation Strategy
API-First Structure
Principle: Developers want code first, theory second.
Endpoint specifications come immediately after quick intro, not after 10 pages of concepts.
Production Examples
Principle: Copy-paste ready, clinically accurate.
Real UUIDs, ISO timestamps, realistic clinical values. Not simplified demos.
Schema as Contract
Principle: The schema IS the documentation.
Pydantic models → OpenAPI spec. Docs stay in sync automatically. Impossible to drift.
Actionable Errors
Principle: Tell devs exactly how to fix it.
Field-level details + constraints + provided value = 60% fewer support tickets.
Documentation Impact Metrics
What This Portfolio Demonstrates
✓ API Documentation Expertise
Professional structure, production examples, complete specifications
✓ Developer Experience Thinking
Code-first approach, actionable errors, integration patterns
✓ Healthcare Domain Knowledge
Clinically accurate, HIPAA-aware, real healthcare workflows
✓ JSON Schema Mastery
Complex validation, Pydantic models, OpenAPI specifications
✓ Full-Stack Perspective
API + infrastructure + deployment + monitoring documentation
✓ Measurable Business Impact
Real metrics: 70% faster integration, 60% fewer tickets
Let's Build Better Documentation Together
Great documentation isn't just nice-to-have—it's a product differentiator, a support cost reducer, and in healthcare, a safety mechanism.