API design has become an unwieldy, overly human-centric exercise that prioritizes complexity over pragmatism. Inspired by the desire to simplify this convoluted space, I’ve introduced a new approach: Rest in Peace API Design, a framework that radically reduces REST complexity while maintaining functionality. This article explores why this method is a much-needed shift, contrasting it with existing guidelines like the Zalando RESTful API Guidelines.
APIs Are for Machines, Not Humans
Developers often forget that APIs are consumed by machines, not by human operators. The machine doesn’t care about nuanced distinctions like POST versus PUT or deciphering myriad date formats. Yet, we build APIs under the illusion of human readability, leading to bloated designs that are hard to maintain and scale.
The Complexity Epidemic
Guidelines like Zalando’s are thorough, yes, but they are also edge-case-driven. By attempting to address every possible scenario, they make API creation cumbersome and error-prone. The resulting APIs often perform suboptimally, are challenging to debug, and ironically require humans to translate them back into machine-compatible formats.
Instead, Rest in Peace API Design aims to eliminate the majority of these issues by providing a pre-defined, clear, and minimalistic framework that prioritizes machine efficiency.
The Core Tenets of Rest in Peace API Design
1. POST-Only Simplicity:
Forget about GET, PUT, and PATCH. All actions are handled through POST, accompanied by a flat, predictable request body. The machine doesn’t need semantic juggling, and neither do we.
2. Flat Paths and Bodies:
Paths like /v1/user/list and flat request/response structures ensure simplicity and predictability.
3. Standardized Time and Formats:
Everything operates in UTC milliseconds, the universal currency of time for machines. This avoids the endless chaos of localized formats.
4. No Redirects, No Ambiguous Status Codes:
Application errors belong in the response body under meta, not in HTTP status codes. Redirects, which introduce security and compatibility challenges, are outright banned.
5. Human-Friendly, Machine-Optimized JSON:
While JSON is retained for convenience, it is streamlined for clarity, reducing the burden on both developers and parsers.
The Value Proposition
1. Eliminates Decision Paralysis
Traditional API design demands constant decision-making on methods, paths, and payloads. With Rest in Peace, the rules are set: follow the guidelines, and stop overthinking.
2. Accelerates Development
By providing a one-size-fits-all structure, developers can focus on functionality rather than API semantics. This significantly reduces time-to-market.
3. Enhances Performance and Reliability
Flat structures and uniform responses make it easier to parse and consume APIs. Machines perform better when they aren’t bogged down by nested objects or unpredictable responses.
4. Reduces Long-Term Maintenance Costs
APIs designed with simplicity and consistency are easier to update, debug, and extend. Unlike legacy designs that feel outdated within years, this approach ensures lasting relevance.
A Pragmatic Library for Java Developers
To further simplify adoption, I’ve created a lightweight library, Type-Map, that handles:
• JSON parsing without reliance on heavyweight libraries.
• Conversion of diverse date formats.
• Value transformation with zero reflection overhead or magic.
This library aligns perfectly with the principles of Rest in Peace API Design, ensuring seamless integration into Java applications.
Why This Matters
APIs should be tools for innovation, not monuments to complexity. By following the Rest in Peace API Design, developers can sidestep years of misguided norms and focus on what truly matters: delivering real value through their services.
Edge cases? Handle them as exceptions, not as a baseline for API design. And yes, your future self will thank you for sparing them the agony of deciphering overly intricate APIs.
Let’s embrace simplicity. Let’s design APIs for machines. Let’s let Rest in Peace.
Explore the Framework: Rest in Peace - GitHub
Try the Java Library: Type-Map - GitHub
What are your thoughts? Does this resonate with your API experiences, or do you see gaps in this approach? Let’s discuss!