RFC 9205 - REST API versioning considered harmful.

[Eric J Bowman <[e-mail]>]

Best practices means putting this in a positive light. I recently searched YouTube for "REST API versioning" and got a plethora of videos to choose from, all along the lines of how to pass a job interview to be a REST API developer. Point #1 is REST = CRUD, I'll tilt at that windmill some other day. Point #2 is REST APIs MUST be versioned. So I commented and got some creator feedback, which I'll anonymously re-use here.



Honestly, I'm more geared towards writing a worst-practices document. I'm not ready to publish my actual text for RFC 9205, just soliciting feedback. Maybe we can address a couple of common arguments in favor of versioning, starting with the easy one: management decided /cart should be /carts, so we had to change our URI allocation scheme from .../v1/... to .../v2/... to reflect this change?



Sigh. HTTP has a concept of redirection. On to a specific example of the "our data format changed" reasoning, this:



payment mode: net banking

Bank name: Bank of America



was changed to this:



payment mode: NB

Bank name: BOA



Sigh. HTTP is an application protocol with some wonderful features many developers miss out on. Say you're changing your API to deprecate some URIs, introduce others, and change from application/xml to application/json. Do you need to change your URI allocation scheme? No. The above change is not at the conceptual layer of resource definition, mapped to URIs.



Deprecated URIs can redirect, or only Accept: application/xml. New URIs could only Accept: application/json. URIs carried over between versions can Accept: application/json, application/xml in that order, with the latter dropped at some future point in time. This allows for incremental change on the client and server sides, and if your resources are defined correctly, you don't need to version your URI allocation scheme. It probably has enough aliases to deal with anyway.



In my case, any file or handle under /var/www may be accessed by one or more protocols including http, ftp, bittorrent, imap, and ya gotta love the kids bringing back gopher... There's already an aliasing issue beyond this, inherent to HTTP as used in the real world... it's been over 20 years since I've included 'www' in a URI, those aliases redirect because there's no 'www' subdomain in my DNS. But, in terms of sysadmin tradition, /var/www it is for shared-over-the-wire resources (even if they're just handles not files), regardless of protocol.



So why square+ your number of HTTP URIs for v2, cube+ for v3, etc.? Yikes. Whole lotta symlinking going on behind-the-scenes, but has the definition of the underlying resource changed? Expanding BOA to Bank of America is at best a change in the schema applied to a known media type, at the representation level -- not the resource level. At worst, application/vnd.api.v{x}+json. If you're versioning your URIs, you're getting REST wrong because you've failed to apply what's probably the primary constraint -- identification of resources -- from which all else follows or none of it would make any sense.



Don't make things hard on maintainers down the road. Ever tried updating PHP code for 8? It's like porting to another language, what with all the enforced syntax changes. Don't be PHP. Do... start by identifying your resources, at the abstract level which applies on the Internet regardless of protocol. What sets HTTP apart is representations -- embrace that.



Do... here's where I have a problem, stating best practices in a positive way which implies the aforementioned don'ts. I'm all ears for a practical reason to version APIs like that, but all I get is weak sauce even from competent coders, somehow this is "received wisdom" on REST which certainly didn't come from Roy. Can the above real-world snippet be used in RFC 9205 to illustrate the sort of change best handled by media types, schema, or Accept headers?



I won't name names of the BigCorp that versioned their API over this syntax change. It's become accepted common practice.


-Eric