This document discusses principles of backwards and forwards compatibility for APIs and web services. It advocates for ignoring unknown data fields rather than validating strictly against schemas. APIs should allow unknown data to be forwarded and gracefully handled rather than causing failures. Standards evolve over time, so strict validation of schemas can break compatibility whereas ignoring extra unknown data preserves it.

1. Versions are evil
Leviticus 0xFEFF
Just after something about shellfish

2. http://api.equestria.magic/v1/

3. COOL URIS DON’T CHANGE

4. Uniform
Resource
Identifier

6. http://v1.api.equestria.magic/

7. URIS ARE OPAQUE
It’s dark in the smuog

8. http://not-so-
opengraph.api.equestria.magic/

11. > GET /rainbow-dash
> Host: api.equestria.magic
> Accept: application/vnd.equestria.ponies.v1+xml
< 200 OK
< Content-Type: application/vnd.equestria.ponies.v1+xml
< ..

12. “We encourage resource owners
to only use true content negotiation
(without redirects) when the
only difference between formats is
mechanical in nature.”
Roy Fielding

13. A conversation I could have had
“User: I need the gravatar of /user/
rainbow-dash
- Me: it’s only in the v2 format
- User: But there’s no @accept on <img>!
- Me: No kidding.”

14. WHY ARE WE THERE?

15. “In the world of Web services, there is a
strong argument that contracts should be
stored and transmitted in a machine-
readable format.”
A guy called Don

16. Frozen in time?

17. Evolution

18. BACKWARD COMPATIBILITY

19. “A product or technology is backward […]
compatible if it can work with input
generated by an older product”
The source of all truths Wikipedia

20. FORWARD COMPATIBILITY

21. “A forward compatible design can accept
data from a future version of itself and pick
out the "known" part of the data”
42 Wikipedia

22. XML Schemas
<xsd:any>
<xsd:anyAttribute>

23. JSON
“No one has been stupid enough yet to
create a JSON schema language”
Delusional person in the street

24. Ignore the unknown
• Degrading when possible
• Ignore what is not understood
.monkey-dash {
coolness: 100%;
}

25. Fallback rules
<input type=“monkey” />

26. DON’T VALIDATE SCHEMAS

27. REALLY, DON’T.

28. Style, or substance
<user>
<address>
Somewhere over the rainbow.
</address>
<monkey-business enabled=“true” />
</user>
Noise
Datum

29. DATUMS DON’T KILL PEOPLE,
SCHEMAS KILL PEOPLE.
Those pesky schemas. Tsk tsk.