Abstract
This document proposes REST++, an evolution of the Representational State Transfer architectural style, designed to address practical shortcomings observed in large-scale API implementations.
REST++ preserves the general philosophy of resource-oriented communication while relaxing several constraints that have proven difficult to apply consistently in modern distributed high-performing systems.
This document is not intended to replace REST, but to extend it in ways that better reflect real-world usage patterns.
1. Background and Motivation
REST, as described in Fielding’s dissertation, introduced a set of architectural constraints intended to guide the design of scalable, evolvable distributed systems. While these constraints were appropriate for the early web, their strict application has become increasingly misaligned with modern engineering realities.
Empirical observation suggests that most production APIs already violate REST constraints in controlled and well-documented ways. REST++ formalizes these deviations, reducing the cognitive overhead associated with pretending otherwise.
2. Terminology
The key words MUST, SHOULD, MAY, SHOULD PROBABLY, and DEFINITELY NOT in this document are to be interpreted as described in RFC 2119, except where overridden by business requirements.
3. Architectural Overview
3.1 REST++ Interaction Model
Figure 1 illustrates the REST++ interaction model.
Unlike REST, REST++ explicitly allows for optional conversational state, provided that the server can “reconstruct intent” when necessary. This is also intended to improve performance as the state is cached and there's no need to retrieve it every time.
4. Core REST++ Extensions
4.1 Optional Statelessness
REST enforces stateless communication. REST++ relaxes this constraint.
Servers MAY retain client context across requests when:
- Latency budgets are tight
- Payload sizes become inconvenient
- The alternative would require clients to “just send everything again”
Clients SHOULD NOT rely on this behavior unless they already do.
This reflects the widely adopted pattern of statelessness with exceptions.
Note: Statelessness violations are no longer violations when documented.
4.2 Extended HTTP Verb Set
REST++ introduces additional HTTP methods to better express intent.
| Verb | Semantics |
|---|---|
| THINK | Server evaluates intent without committing |
| MAYBE | Operation MAY occur depending on server mood |
| EVENTUALLY | Asynchronous execution with no SLA |
| FIX | Server applies heuristics to reach a “better” state |
| UNDO | Best-effort rollback of something that probably cannot be rolled back |
These verbs are intentionally non-idempotent unless they accidentally are.
4.3 Resource Verb Duality
REST++ removes the strict noun-only restriction on resource naming.
Resources MAY be verbs if:
- The domain language already uses verbs
- Modeling them as nouns would require an extra explanation slide
- The endpoint name “reads better”
Examples of valid REST++ resources:
POST /borrowBook
POST /approveUser
POST /syncEverything
POST /doTheThing
This avoids unnecessary reification of abstract concepts such as “borrowings,” which users did not ask for.
Rationale: If it works in controllers, it should work in URLs.
4.4 Implicit Version Negotiation
REST++ eliminates explicit versioning.
Instead:
- Clients always interact with the “current” API
- Breaking changes are handled server-side
- Compatibility is maintained through conditional logic and hope
Version identifiers such as /v1, /v2, or headers like Accept-Version are discouraged, as they encourage long-term thinking.
Implementation Note:
Rollbacks are handled operationally.
4.5 Relaxed Uniform Interface
REST enforces a uniform interface across resources. REST++ allows resource-specific interaction contracts.
Each endpoint may define:
- Custom semantics
- Domain-specific error codes
- Payload formats that “feel right”
Consistency is encouraged but must not impede velocity.
5. Error Handling
REST++ simplifies error handling by reducing semantic obligations.
Recommended approach:
- Return
200 OKwhenever possible - Include error details in the payload
- Use
500for everything else
This aligns error semantics with how clients already behave.
6. Security Considerations
REST++ does not mandate a specific authentication or authorization strategy.
Security SHOULD be handled:
- At the edge
- In middleware
- Somewhere else
Authorization is considered an orthogonal concern and SHOULD NOT influence resource design, endpoint naming, or access control decisions.
7. Migration Strategy
Existing REST APIs may migrate incrementally to REST++.
Suggested steps:
- Rename endpoints to better reflect intent
- Introduce implicit state where convenient
- Remove explicit versions
- Add semantic verbs sparingly but confidently
Backward compatibility SHOULD be preserved until it is no longer needed.
8. Discussion
REST++ does not claim to be purer than REST. It claims to be honest.
By acknowledging common deviations and standardizing them, REST++ reduces architectural guilt and increases delivery confidence while increasing the delivery speed.
9. Known Limitations
- REST++ may be difficult to distinguish from RPC
- Tooling support is currently informal
- Some REST purists may experience discomfort
- Since this was posted on April 1st, it should not be taken seriously
9. Conclusion
REST++ represents a pragmatic evolution of REST, informed by years of production experience and organizational realities.
While it diverges from original REST constraints, it reflects how APIs are actually designed, deployed, and maintained today.
Modern Software Engineering practices dictate that everything can be handed over to a Large Language Model (LLM) to re-generate the API design when it stops serving its purpose and we encourage the API users to do the same with their API clients.
Everything written in this document is not to be taken seriously as it is 1st of April and the world goes crazy in this date.