Versions are evil
Leviticus 0xFEFF Just after something about shellfish
http://api.equestria.magic/v1/
COOL URIS DON’T CHANGE
Uniform
Resource
Identifier
http://v1.api.equestria.magic/
URIS ARE OPAQUEIt’s dark in the smuog
http://not-so-opengraph.api.equestria.magic/
> GET /rainbow-dash > Host: api.equestria.magic > Accept: application/vnd.equestria.ponies.v1+xml
< 200 OK < Content-Type: application/vnd.equestria.ponies.v1+xml < ..
“We encourage resource ownersto only use true content negotiation (without redirects) when the only difference between formats is mechanical in nature.”
Roy Fielding
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.”
WHY ARE WE THERE?
“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
Frozen in time?
Evolution
BACKWARD COMPATIBILITY
“A product or technology is backward […] compatible if it can work with input generated by an older product”
The source of all truths Wikipedia
FORWARD COMPATIBILITY
“A forward compatible design can accept data from a future version of itself and pick out the "known" part of the data”
42 Wikipedia
XML Schemas
<xsd:any> <xsd:anyAttribute>
JSON
“No one has been stupid enough yet to create a JSON schema language”
Delusional person in the street
Ignore the unknown
• Degrading when possible • Ignore what is not understood.monkey-dash { coolness: 100%; }
Fallback rules
<input type=“monkey” />
DON’T VALIDATE SCHEMAS
REALLY, DON’T.
Style, or substance
<user> <address> Somewhere over the rainbow. </address> <monkey-business enabled=“true” /> </user>
Noise
Datum
DATUMS DON’T KILL PEOPLE, SCHEMAS KILL PEOPLE.
Those pesky schemas. Tsk tsk.