The Monday We Built Something Overly Complex
It was February 2022 at Exclusive IT Solutions. We were designing an API to integrate with a healthcare provider's systems.
Their system was complex. Their data model was intricate. Their business logic was sophisticated.
We designed our API to match that complexity. We created intricate endpoints. We built elaborate request/response structures. We implemented sophisticated validation.
It was elegant. It was powerful. It was completely understandable to developers.
Two months later, we started integrating. The healthcare provider's team struggled.
"This is too complex," their lead developer said. "We can't integrate with this efficiently."
"But our API matches your complexity," I argued. "We designed it to handle all your edge cases."
"Yes," he said. "But integrating with simple APIs is faster. Integrating with complex APIs takes months."
We had built a powerful API that was too complex to use efficiently.
The Metaphor: The Standard Shipping Container vs. The Custom Crate
Let me explain with a metaphor that transformed my API design philosophy.
Custom, complex APIs are like custom-built shipping crates.
You have something to ship. You build a perfect crate for it. Custom dimensions. Specialized features. Optimized for exactly what you're shipping.
It's perfect for your one shipment. But then:
- Different trucks can't carry it (doesn't fit standard sizes)
- Different warehouses can't stack it (doesn't fit standard systems)
- Different teams can't load it (requires special knowledge)
- Any change requires rebuilding everything
RESTful APIs are like standard shipping containers.
They're a standard size. They have standard features. They work with any truck, any warehouse, any team.
They're not optimized for any one shipment. But they work for every shipment.
In business integrations, you rarely ship one thing. You ship many things, repeatedly, with different partners.
Standard containers (RESTful APIs) work better than custom crates (complex APIs).
The Struggle: The "Complexity Equals Capability" Mindset
I'll be honest: I equated complexity with capability.
If an API had intricate request structures, sophisticated validation, elaborate response formats—I thought it was a better API.
Simple APIs felt... inadequate. Like we hadn't thought about edge cases. Like we weren't being thorough.
But here's the truth: complexity in API design is rarely capability. It's usually just complexity.
The Transformation: RESTful Simplicity
I implemented a shift in our API design philosophy. We embraced RESTful principles.
What Is REST? (Simple Explanation)
Technical: Representational State Transfer—an architectural style for distributed hypermedia systems
Simple: A set of conventions for building predictable, standard APIs
Key principles:
- Resources, not actions: APIs represent resources (patients, appointments, records) not actions (addPatient, bookAppointment)
- Standard methods: Use standard HTTP methods (GET for retrieve, POST for create, PUT for update, DELETE for delete)
- Stateless: Each request contains all information needed—no server-side session state
- Consistent: Same patterns across all endpoints
Why RESTful Wins for Business Integrations
1. Predictability
If you've used one RESTful API, you've used them all.
Before our complex API: Each endpoint was unique. Integration team had to learn each one from scratch.
After our RESTful API: All endpoints follow the same pattern. Integration team learned the pattern once and applied it everywhere.
2. Standard Tooling
Every modern programming language has excellent REST client libraries. Every API testing tool supports REST.
Before: Custom integration tools, custom client code, extensive testing overhead
After: Standard libraries, existing tools, minimal testing overhead
3. Documentation
RESTful APIs are self-documenting. Resources are obvious. Methods are standard.
Before: Extensive documentation needed for every endpoint's unique behavior
After: Standard documentation structure, most of which writes itself
4. Integration Speed
Predictable patterns + standard tooling + self-documenting = faster integration
Before our complex API: 4 weeks to integrate with healthcare provider
After our RESTful API: 1 week to integrate with healthcare provider
75% faster integration.
The Real-World Example: The Patient Data API
Let me share the transformation from complex to RESTful.
The Complex API (What We Initially Designed)
Endpoints:
/createPatient- POST with complex nested structure/updatePatientFields- POST with field-specific logic/getPatientDemographics- GET with demographic-specific filtering/getPatientMedicalHistory- GET with medical-specific filtering/getPatientInsurance- GET with insurance-specific filtering/addPatientAppointment- POST with appointment-specific logic/updatePatientAppointmentStatus- POST with status-specific logic
Problems:
- Each endpoint was unique—no consistent patterns
- Integration team had to learn each endpoint individually
- Changes required updating multiple endpoints
- Documentation was extensive but not helpful
The RESTful API (What We Redesigned)
Endpoints:
GET /patients- Retrieve list of patientsPOST /patients- Create new patientGET /patients/{id}- Retrieve specific patientPUT /patients/{id}- Update specific patientDELETE /patients/{id}- Delete specific patientGET /patients/{id}/appointments- Retrieve patient's appointmentsPOST /patients/{id}/appointments- Create appointment for patient
Benefits:
- Consistent pattern across all endpoints
- Integration team learned the pattern once
- Changes were localized
- Documentation was minimal yet comprehensive
Resource-based design:
- Patients are a resource
- Appointments are a sub-resource of patients
- All resources follow the same pattern
The Results: Measurable Impact
Integration Time
Complex API: 4 weeks to integrate with healthcare provider RESTful API: 1 week to integrate with healthcare provider Improvement: 75% faster
Integration Quality
Complex API: 8 integration bugs found, 4 of which were in production RESTful API: 2 integration bugs found, both caught in development Improvement: 87% fewer bugs
Documentation Size
Complex API: 45 pages of API documentation RESTful API: 12 pages of API documentation (80% covered by self-documenting) Reduction: 73% less documentation to maintain
Maintenance Effort
Complex API: 2-3 days for any API change (multiple endpoints affected) RESTful API: 0.5-1 day for any API change (localized changes) Reduction: 70% less maintenance effort
The Metaphor: The Universal Plug
I like to explain the value of RESTful APIs with this metaphor:
Custom APIs are like proprietary power adapters. They work perfectly with your devices. But anyone else's devices need custom adapters too. Integrating everyone requires custom adapters for everyone.
RESTful APIs are like USB. Everyone agrees on the standard. Everyone builds to the standard. Integrating is plugging in—no custom work required.
USB isn't optimized for any one device. But it works for all devices.
In business integrations, you're rarely integrating with one system. You're integrating with many systems, over time, with different partners.
Custom APIs (proprietary adapters) work great initially but become maintenance nightmares.
RESTful APIs (USB) might not feel optimized initially, but they scale beautifully.
Common Mistakes to Avoid
Mistake 1: Designing Actions Instead of Resources
Wrong: /addPatient, /updatePatient, /deletePatient Right: POST /patients, PUT /patients/{id}, DELETE /patients/{id}
Why: Resources, not actions, are predictable.
Mistake 2: Over-Complicating Request/Response Structures
Wrong: 10 levels of nesting, extensive optional fields, complex validation rules Right: Flat structures, reasonable nesting, simple validation
Why: Simplicity enables faster integration.
Mistake 3: Not Using Standard HTTP Methods
Wrong: Using POST for everything, custom headers for action indication Right: GET (retrieve), POST (create), PUT (update), DELETE (delete)
Why: Standard methods are predictable and well-supported.
Mistake 4: Inconsistent Patterns
Wrong: Each endpoint follows different conventions Right: All endpoints follow the same convention
Why: Consistency means learn once, apply everywhere.
Mistake 5: Ignoring RESTful Constraints
Wrong: Stateful operations, custom method semantics, non-standard status codes Right: Stateless operations, standard method semantics, standard status codes
Why: These constraints are what make RESTful APIs beneficial.
The Hard Truth
In API design, complexity is rarely capability. It's usually just complexity.
I've seen incredibly complex APIs that were "powerful" but took months to integrate. I've seen simple RESTful APIs that integrated in days and worked perfectly.
For business integrations, the best API isn't the most powerful or most sophisticated. It's the most predictable and easiest to integrate.
Simplicity wins.
A Framework for Your API Design
If you're designing APIs for business integration:
Principle 1: Resources, Not Actions
Design around what you're modeling (resources), not what you're doing (actions).
Principle 2: Standard Methods
Use GET, POST, PUT, DELETE as they're intended.
Principle 3: Consistent Patterns
All resources follow the same patterns.
Principle 4: Simple Structures
Flat request/response structures. Reasonable nesting. Simple validation.
Principle 5: Standard Codes
Use standard HTTP status codes (200, 201, 400, 404, 500).
What's your experience with API design? Have you built overly complex APIs?
#RESTAPIs #SystemIntegration #BestPractices #APIDesign #IntegrationStrategy