More On REST Versioning: Your API Is Not Your Schema

This is a follow up to last week’s post about REST versioning.

When we talk about versioning of API’s, we need to actually clarify something. You can version an entire API or version individual resources. When you change the schema of returned objects identified by a URI, that’s a problem with individual resource version. If you change the available endpoints and operations, that’s a problem with API version. The two should not be conflated. (see discussion points here and here.)

I think that’s what Roy Fielding meant when he said “Don’t version your API.” The API is your set of endpoints and operations, and they are identified dynamically by providing links (controls) dynamically. There’s a distinction between that and versions of data structures returned by your API. The latter are versioned by content type, since if the structure changes, it’s a different format of data just as an XML document is a different format from a PNG.

So let’s take a step back and ask: Does it even make sense to have different versions of these resources? If you changed the format of a certain resource, certainly an un-updated client that doesn’t know about a new schema could still use of the old format and ask for it by name, and new clients would want to use the new format. But in your server side code, you’ll still have to have two different DTO classes for each representation. I would argue that the new version is actually a new resource representing new information, and should therefore have a new URI entirely.

With this way of thinking, you could advertise the old object/URI as deprecated, and your versioning becomes simply deprecating URI’s that are not accessible from your main API over time. Any clients that access URI’s directly (i.e. not through the hypermedia controls you provide) would be responsible to update themselves.

What do you think? Is this a reasonable approach to versions and your API? As a thought experiment, what do you think would happen if you used your API version to version your data structures?

Leave a comment

Filed under Software Engineering

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s