The earlier archive Written for a different audience — operations teams, business stakeholders, new joiners. It is kept unchanged, with its original date, because a dated body of work says something a rewritten one cannot.

RESTful APIs: Why Simplicity Wins in Business Integrations

It was February 2022 at Exclusive IT Solutions. We were designing an API to integrate with a healthcare provider's systems.


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 patients
  • POST /patients - Create new patient
  • GET /patients/{id} - Retrieve specific patient
  • PUT /patients/{id} - Update specific patient
  • DELETE /patients/{id} - Delete specific patient
  • GET /patients/{id}/appointments - Retrieve patient's appointments
  • POST /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

The archive

Every article, 2013–2026

Thirty dated articles on application support, delivery, infrastructure and data — plus the recent writing on CI/CD reproducibility and offline-first design.

The recent work is written for a specialist audience, and it is where the measurement discipline is set out in full.

Recent writingOpen Source Impact