News for hackers. Stuff that matters.
Re:How to Version an API by smizell on Thursday June 08, 2017 @03:59PM (#14516766)
I personally like to think about managing change well rather than versioning an entire API. In this, API designers provide instructions on how APIs will evolve over time, how features will be deprecated, and how this process will be communicated to API consumers. Change management also includes recommendations for client developers on how to evolve along with the API and build clients that don't fail when something as small as a JSON property is absent or added. You don't necessarily need version numbers to do this.

An API version says to me that one day the entire API may introduce a major change that is separate from the current API. If you plan to never introduce a major change like this, you may not need a "/v1" in the URL.

Kudos to the author for putting together a nice article :)

Re:How to Version an API by tetraodonpuffer on Thursday June 08, 2017 @05:21PM (#14517283)
API consumers might also not be very flexible when it comes to adapting to API changes: some might have developed fragile/inflexible code that will go up in flames if you even add a new field to an object (leading to support calls and escalations), this is why depending on your domain you might need very strict versioning requirements.

Some APIs will not change a version number even if new objects/fields are added, others will, it really depends by what space you are in and your customer needs and it should be taken into account when designing your API.

Re:How to Version an API by smizell on Thursday June 08, 2017 @05:30PM (#14517341)
I think you are right here. It takes two to tango, and if the clients are tightly coupled to the API, the best intentions for evolving slowly will fail. :)
Re:How to Version an API by nradov on Thursday June 08, 2017 @04:29PM (#14516956)
Never say never. It's generally impossible to predict how an API will have to evolve over time in response to changing requirements.
Re:How to Version an API by smizell on Thursday June 08, 2017 @04:35PM (#14516996)
That's true. However, I think this falls under YAGNI [0]. If you happen to get to a point where you have to change your an entire API rather than evolve what you have, you should consider it a new, separate API rather than instruct all client developers to plan for it up front. Plan for evolvability and handling changing requirements up front.

[0] https://martinfowler.com/bliki/Yagni.html

Re:How to Version an API by ljcrabs on Friday June 09, 2017 @02:02AM (#14519445)
And how would you name this new API? Bob? Or version 2?
Re:How to Version an API by smizell on Friday June 09, 2017 @09:53AM (#14521350)
Name it whatever you want. Point is, you don't have to plan for such a drastic change when a separate domain/subdomain will solve it for you.
Re:How to Version an API by _pmf_ on Friday June 09, 2017 @02:21AM (#14519511)
As an API consumer, clean cuts are much, much more manageable than a continuous stream of small breakages.
Re:How to Version an API by smizell on Friday June 09, 2017 @10:15AM (#14521498)
True. I would consider a continuous stream like that to not be helpful change management. But if you have to have continuous breaking changes like that, you would want clean cuts. My point is, find ways to evolve your API without breaking things.
Re:How to Version an API by aantix on Thursday June 08, 2017 @03:19PM (#14516443)
If you're a Rails dev, take a look at VersionCake.

It allows you to version your json Jbuilder views by adopting the file naming convention (e.g. show.json.v1.jbuilder, show.json.v2.jbuilder, etc).

There's fallback to most recent, compatible version of the API.

https://github.com/bwillis/versioncake

Re:How to Version an API by pchristensen on Thursday June 08, 2017 @05:19PM (#14517277)
I was like, Who's recommending VersionCake? But it's none other than Jim Jones!
Re:How to Version an API by armandososa on Thursday June 08, 2017 @06:00PM (#14517502)
Offtopic: I was amazed by the quality of the illustrations and was pleasantly surprised to find that the woman who makes the illustrations (https://twitter.com/annieruygt) is listed on the company's about page.
Re:How to Version an API by mrkurt on Thursday June 08, 2017 @06:29PM (#14517660)
Annie's amazing!
Re:How to Version an API by defanor on Friday June 09, 2017 @04:01AM (#14519889)
The title is a bit misleading: the article is about HTTP-based API versioning, not just any kind of API. A more generic approach that would fit such a title is "semantic versioning" [1], which covers different questions.

[1] http://semver.org/

Re:How to Version an API by wst_ on Friday June 09, 2017 @06:14PM (#14525005)
Yeah. People should stop saying API for a HTTP API. This is an application programming interface. Any application.
Re:How to Version an API by eridius on Thursday June 08, 2017 @04:16PM (#14516887)
> Header versioning in the wild is primarily done via a customized Accept HTTP header.

Is this true? I haven't looked at very many web APIs, but I haven't run across anyone using Accept in this way, and it strikes me as a pretty bad mis-use of that header.

Re:How to Version an API by Dirlewanger on Thursday June 08, 2017 @04:57PM (#14517141)
How is it a bad misuse? It's used to specify the MIME type. Why is it so much of a stretch to also specify which version of the MIME type to use? I personally think this is the cleanest and most unobtrusive way to version an API. I'd rather change that than have to change the URL all the the time. Not to mention that /api/vX/... is just ugly.
Re:How to Version an API by saurik on Thursday June 08, 2017 @07:08PM (#14517890)
I don't understand how changing one or the other of these things is somehow easier, nor does it make sense to try to claim one or the other is "ugly"... seriously? Do you even see these requests? I just don't understand this thought process.
Re:How to Version an API by eridius on Thursday June 08, 2017 @06:50PM (#14517773)
The Accept header specifies the acceptable MIME types for the response. It doesn't specify how the request itself is supposed to be interpreted. Picking between alternate MIME types with the Accept header is still supposed to give you the same content, just in different representations.

The proper solution here is to just define a new header, like X-API-Version (note: the article picked a header API-Version, but since this is a non-standard vendor-specific header it should be prefixed with X-).

Re:How to Version an API by gnaritas on Thursday June 08, 2017 @07:02PM (#14517866)
A different version is just a different representation of the same resource, the Accept header is the correct way to do it.
Re:How to Version an API by eridius on Thursday June 08, 2017 @08:44PM (#14518393)
If the only difference is the data returned, and not anything to do with how the request is actually interpreted, then I guess it works. But API versioning covers more than just changing the fields in the JSON response.
Re:How to Version an API by gnaritas on Friday June 09, 2017 @12:40AM (#14519210)
If the client knows the version to send, they can send a different request format as well and you'll know how to interpret it due to the version header; that header isn't just used for the response, it's an agreement about what the specific message format in both directions is. If he's looking for a version 5 response then parse it as a version 5 request. I don't see the problem? Now your media types and versions of those types can vary and grow without messing with your resource locations which can remain stable. Beyond that you can now version each resource independently rather than forcing the app as a whole to change.
Re:How to Version an API by eridius on Friday June 09, 2017 @01:02AM (#14519275)
Your problem is you're taking a header that's explicitly intended for selecting among multiple response types, and using it to control how the request itself is processed. That's simply incorrect. That's not what the Accept header is meant to do, and using it that way is confusing.

> that header isn't just used for the response, it's an agreement about what the specific message format in both directions is

No, it's not. The Accept header is strictly about the response.

Re:How to Version an API by growse on Friday June 09, 2017 @06:58AM (#14520525)
A lot of the time, "breaking the API" means "breaking the response that comes back", which in turn means that the client doesn't know what to do with the response (can't parse it, missing fields, different schema etc.).

If I change my API so that "POST /widgets" does something different on the backend but returns the same response, then from a client compatibility perspective this isn't a breaking change.

Re:How to Version an API by pvorb on Friday June 09, 2017 @03:03AM (#14519632)
Yep, you should also send a Content-Type if your request has a body.
Re:How to Version an API by gnaritas on Friday June 09, 2017 @10:58AM (#14521835)
> No, it's not. The Accept header is strictly about the response.

OK, if you want to be that strict about it, then you use both the ContentType and Accept headers to specify what version of the request and response you're making/wanting.

Re:How to Version an API by eridius on Friday June 09, 2017 @02:44PM (#14523463)
The Content-Type specifies the MIME type of the body content. So even that's not good enough for actually interpreting the URL or URL parameters. Content-Type would only work if all of your APIs go through the same URL and strictly use the body content for the actual request (which would be a pretty awful API).
Re:How to Version an API by gnaritas on Friday June 09, 2017 @02:52PM (#14523525)
Fair point; I still say if you're requesting version 5 response then the server can interpret the request as version 5 as well and act accordingly, they're necessarily linked regardless of the Accept header being about the response; it must necessarily imply the request URI version format.
Re:How to Version an API by eridius on Friday June 09, 2017 @02:57PM (#14523555)
I can see why you're saying that, but I still disagree that this is a valid usage of Accept, and at a minimum it's going to be confusing, because nobody expects the Accept header to affect interpretation of the request.

I'm also not sure why anyone would even want to use Accept for this, given that if you can set Accept, you can also set something like X-API-Version.

Re:How to Version an API by gnaritas on Friday June 09, 2017 @06:46PM (#14525143)
It's not only a valid usage of accept, it's simply necessary; you can't possibly process a request for a version of a response without assuming the request contains the necessary information said response requires. If you don't expect the Accept header asking for a specific version to affect the processing of the request, I think you really haven't thought it through as it necessarily must since the output response version must be correlated with the input request. If output version 5 requires a different set of input args, then your code for processing the output will have to assume those args present and thus will have to assume the request was formatted correctly for version 5 otherwise you'll have to throw an error saying the request was formatted incorrectly.

Yes, you could use a custom header, many do, but then you're stepping outside of the HTTP standard, the Accept header is supposed to define the response format, not some custom one you make up, and version is another facet of the response format and must imply the request format matches the required data of the requested output format.

Re:How to Version an API by eridius on Friday June 09, 2017 @08:01PM (#14525456)
...what? Your comment literally makes no sense to me.

> Yes, you could use a custom header, many do, but then you're stepping outside of the HTTP standard

No you're not. The HTTP standard allows for custom headers, and nothing in the HTTP standard restricts servers from using customer headers to influence how they process the request.

> Accept header is supposed to define the response format

Yes, like application/json. It's not supposed to define the request content, just the format, and it's definitely not supposed to affect the way the request is processed.

> version is another facet of the response format

No it's not. JSON is a response format. XML is a response format. "API version 5" is not a response format.

Re:How to Version an API by jalfresi on Friday June 09, 2017 @04:00AM (#14519881)
The mime-type has changed. How you interpret the mime-type has changed.
Re:How to Version an API by solatic on Friday June 09, 2017 @02:07AM (#14519460)
Because the version of the API is not the version of the MIME type. It's not like JSON itself came out with version 2 of the JSON specification.
Re:How to Version an API by jalfresi on Friday June 09, 2017 @03:58AM (#14519873)
Look at the mime-type declaration again - its not application/json. It is a representation of a resource in JSON format. The resource is the part thats changed, and interactions with that resource are defined as part of the mime-type.
Re:How to Version an API by greencurry43 on Thursday June 08, 2017 @04:30PM (#14516962)
I've seen some use a versioned media typed like GitHub [0] or add a version parameter like "vnd.example-com.foo+json; version=1.0" [1]. People may use this version for the entire API or for versions of that specific resource as well.

[0] https://developer.github.com/v3/media/ [1] http://blog.steveklabnik.com/posts/2011-07-03-nobody-underst...

Re:How to Version an API by hdhzy on Thursday June 08, 2017 @03:05PM (#14516333)
Roy Fielding himself had an interesting interview [0] where versioning a REST API was one of the topics (spoilers: version is not in the url nor headers).

[0]: https://www.infoq.com/articles/roy-fielding-on-versioning/

Re:How to Version an API by eriknstr on Thursday June 08, 2017 @03:18PM (#14516436)
> My point was that there is no need to anticipate such world-breaking changes with a version ID. We have the hostname for that. What you are creating is not a new version of the API, but a new system with a new brand.

I think Rich Hickey (the creator of Clojure) would agree. He said something to this effect in the "Spec-ulation" keynote at Clojure/conj 2016. https://www.youtube.com/watch?v=oyLBGkS5ICk

Re:How to Version an API by deathanatos on Thursday June 08, 2017 @04:42PM (#14517035)
I'm going to have to disagree with him. If I need to break compatibility on a single resource, I don't want to mirror every API endpoint (except that one) to a new hostname. That becomes continually more and more complex and hard to keep sense of as changes progress.

The hostname thing might work for huge, world-changing re-writes, but for small, incremental changes, I think something like what GitHub does w/ the Accept header is far more appropriate.

Re:How to Version an API by prebrov on Friday June 09, 2017 @01:48AM (#14519401)
His argument is for API discoverability. Client should be able to learn about available endpoints

[edit: ...and resources. And be able to comprehend resource record conventions]

Re:How to Version an API by deathanatos on Friday June 09, 2017 @03:18PM (#14523692)
I also don't see the point of API discoverability, at least, not programmatically. Sure, such a thing could be built, but I don't know what could be done w/ the results. Most API's I've ever worked on required domain knowledge in order to operate on (e.g., you had to understand the content — semantically — of the result. I.e., you needed to understand what a `applicaiton/vnd.bigcorp.widget.v2+json` was.)

I just don't see any generic operations w.r.t. discovery that are … useful.

I'm not trying to say that you shouldn't, e.g., use URLs in your resulting resources; e.g., if a query for a widget returns:

  {
    "widget_name": "NextGen Enterprise Widget",
    "suppliers": "http://bigcorp.example.com/widget/123/suppliers"
  }
That's fine. But you're still going to need to know how to parse the result of …/suppliers, or it's just opaque bytes.
Re:How to Version an API by BillinghamJ on Thursday June 08, 2017 @03:03PM (#14516322)
Currently I structure my URLs like this:

    /v1/2017-06-08/blah
The idea is that you write in the date that you wrote the implementation against the API. This is just like Stripe's API, but explicit rather than implicit. Then everything under that will continue to work as-is.

There's a few reasons I like to do this, but the main one is that I often struggle to decide whether a given change is really "worthy" of a major version change.

The only rule/caveat we have is: within a given client's implementation, you should only use one date at a time. Mixing them creates a small possibility of compatibility issues.

The initial /v1/ is just in case I decide to move away from the date thing at some stage.

Re:How to Version an API by edoceo on Thursday June 08, 2017 @03:12PM (#14516386)
I'm similar but just prefix like

    /v2014
I assume I won't make multiple versions in a year. I have a current system with /v2014, /v2016 and /v2017

I like to smash dates into all my version strings

Re:How to Version an API by cyann on Thursday June 08, 2017 @03:31PM (#14516531)
Yes, human readable dates are very good at conveying a sense of obsolescence.

Mine are a bit more granular: /vyymm, e.g. /v1503, /v1610, /v1706. This should work well for this century ;-)

Re:How to Version an API by SamUK96 on Thursday June 08, 2017 @04:44PM (#14517053)
> 3: RESTful. It should speak the language of HTTP verbs: GET, PUT, POST, PATCH, UPDATE, DELETE.

I know it's slightly off-topic, but when one of the early points of an article contains an incorrect piece of information, that really makes me not want to read on further

Restful API's are a recent "fad" that, even though_do_ have their place in mainly basic CRUD apps, RPC still reigns very popular. See [1] for a pretty good explanation of REST-styled vs RPC-styled APIs.

[1] https://www.linkedin.com/pulse/rest-vs-rpc-soa-showdown-josh...

Re:How to Version an API by tracker1 on Thursday June 08, 2017 @07:27PM (#14517992)
I've rarely seen a "pure" API that wasn't also very simplistic... most composite APIs of any complexity have things that work better as an RPC request (via HTTP POST) as well as other more restful endpoints.
Re:How to Version an API by smnscu on Friday June 09, 2017 @03:09AM (#14519650)
Wrt your users, I think regardless of what scheme you use for API versioning it's a good idea to build libraries to access it – if you can afford it. [Go :), ]JS, PHP, C#, Java, Python, and Ruby, and you have most of the market covered. Then you can use semver for the libraries and the user doesn't care about how the actual endpoints look like – as an added bonus you can use more efficient encodings.

Example from a past life: https://github.com/lavab/api-client-js

Re:How to Version an API by loup-vaillant on Thursday June 08, 2017 @04:17PM (#14516891)
Great, I was wondering how to version my library once I reach 1.0.

> 3: RESTful. It should speak the language of HTTP verbs: GET, PUT, POST, PATCH, UPDATE, DELETE.

Oh, it was talking about web interfaces. Oh well.

Re:How to Version an API by tracker1 on Thursday June 08, 2017 @07:25PM (#14517980)
Is there a reason you can't use semver? Or was this just a quippy remark?
Re:How to Version an API by loup-vaillant on Friday June 09, 2017 @03:52AM (#14519852)
This article isn't even about semantic versioning. It is exclusively about web API design and versioning, and the web doesn't interest me.

API used to mean headers, types, Java interfaces… stuff programmers use to link code together. And now the web is hijacking the term to a point where regular APIs can't even be named. I mean, can web developers even think about this kind of API now?

I bet this explains part of the microservice madness we've seen lately. If the only kind of API you know goes through a web server, of course you'd use not-so-micro-services to modularise your application.

Re:How to Version an API by tracker1 on Friday June 09, 2017 @02:37PM (#14523414)
My point was, that if it came to versioning API library versions, then "just use semver" would seem to be the most appropriate answer. I understand the conflation between "web api" and "api" here, I feel the same when "Microsoft SQL Server" is referred to as simple "SQL Server"
Re:How to Version an API by loup-vaillant on Friday June 09, 2017 @05:57PM (#14524909)
I do intend to "just use semver". I was just hoping this article would give me something more.
Re:How to Version an API by pixelcort on Thursday June 08, 2017 @05:41PM (#14517389)
How about systems like GraphQL where the client specifies the attributes to be returned? To deprecate an attribute, just mark it as deprecated and wait until no client is requesting that field.
Re:How to Version an API by pluma on Friday June 09, 2017 @04:44AM (#14520069)
> just

No. Marking something as deprecated helps during development. It doesn't help if it's a bunch of deployed code running in production that nobody has the time to maintain for third-party changes. That code will keep making those requests until they fail.

GraphQL inherently doesn't address versioning. You'd have to version each attribute and query separately by prefixing or suffixing their names. But then you'd lose the succinctness GraphQL users love it for.

The official answer is "Just add new attributes" but that means you're stuck coming up with new names for slightly different versions of existing attributes (or queries). If you try to "be bold" and make things up as you go along, your API will be littered with the equivalent of `2017-06-09_docs_final_v2_new_copy.pdf` if you take backwards compatibility serious.

Seeing how Relay is slowly turning GraphQL APIs into RPC APIs ("client sends complex query blob with parameters to server" has become "client sends query ID with parameters to server", server-side GraphQL is now an implementation detail only relevant during development), maybe the right question to ask is:

How do I version an RPC API?

Re:How to Version an API by gnaritas on Thursday June 08, 2017 @07:28PM (#14517995)
You'll be waiting possible forever, clients tend to not change until forced to.
Re:How to Version an API by Moru on Friday June 09, 2017 @01:43AM (#14519383)
And why should they? They probably hired some developer to make the application and this developer might not be available any more. Are you forcing the user to change or are you liberating the user to move to a new company with similar services? If you want your customer to stay with you, make sure it is as frictionless as possible to stay with your service. Of course, if the change is because of security you have to be more clear about it but change just for change sake is dangerous.
Re:How to Version an API by gnaritas on Friday June 09, 2017 @02:55PM (#14523543)
Oh I agree, you should support them as long as you reasonably can if their business justifies the expense and complexity of maintaining multiple versions. At some point it eventually won't, and that's when you force them to upgrade or lose access.
Re:How to Version an API by paulddraper on Thursday June 08, 2017 @07:32PM (#14518020)
> RESTful. It should speak the language of HTTP verbs: GET, PUT, POST, PATCH, UPDATE, DELETE

What in the heck is UPDATE? It sounds like a non-technical person found out REST had CRUD.

Re:How to Version an API by itcmcgrath on Thursday June 08, 2017 @07:38PM (#14518047)
It's the verb you use when you want to receive a 400 with "BAD Request - Invalid verb"
Re:How to Version an API by jholman on Friday June 09, 2017 @07:32AM (#14520645)
There's nothing RESTful about using more than 2 HTTP verbs (GET for SAFE endpoints, and POST for UNSAFE ones). (Mind you, REST does require that you obey the semantics of HTTP for the verbs that you do use, standard or non-standard).

And then the API endpoints illustrated don't obey HATEOS. So there's nothing RESTful about the article either.

Re:How to Version an API by jalfresi on Friday June 09, 2017 @04:01AM (#14519894)
You can define your own HTTP verbs if you want
Re:How to Version an API by abraae on Thursday June 08, 2017 @09:01PM (#14518453)
But failed to also add INSERT.
Re:How to Version an API by vincentmarle on Thursday June 08, 2017 @03:29PM (#14516514)
> When you construct an API, you receive scalability and load balancing benefits by decoupling your API and hosting it as its own backend

I've thought about doing this a couple of times but it seems like a lot of overhead if you need to have separate production instances running for each version of your API.

Is there a better approach to organize this in a more scalable manner?

Re:How to Version an API by rockostrich on Thursday June 08, 2017 @04:02PM (#14516791)
The two options are have the different versions running on separate instances or have all versions in a single instance. The former lets you scale the versions independently. If v1 traffic drops 5x overnight then you can scale it down by 5x. The latter simplifies the deployment and management though. You just have to deploy one service and scale one service to a single amount of traffic.
Re:How to Version an API by faitswulff on Thursday June 08, 2017 @06:55PM (#14517813)
Random thought, but would it make sense to give each client a unique base path for URL endpoints and let them instantiate new endpoints with different versions?

Ex:

    mysite.com/api/UUID_for_api_v1/cars/1
and

    mysite.com/api/UUID_for_api_v2/automobiles/1
Re:How to Version an API by caffeinewriter on Thursday June 08, 2017 @07:05PM (#14517877)
I was just thinking about this. Instead of versioning with an `Accept` header, or with a URL version, why not version off of an upgradable API key?
Re:How to Version an API by TimWolla on Thursday June 08, 2017 @07:29PM (#14518005)
Facebook does this partly: Each “Application” has an associated API version which is the earliest API version that can be accessed (and IIRC the one used implicitly when no version is given inside the route).
Re:How to Version an API by jcrites on Thursday June 08, 2017 @04:50PM (#14517090)
What I've learned about API versioning:

1. Versioning an entire web service or RPC API is relatively expensive in terms of engineering resources. Wherever possible, avoid having more than one version of an API, in favor of a single API version that evolves gradually in backwards-compatible ways. Having multiple API versions is a recourse to employ when you've realized that the original API isn't ideal, and you need to break compatibility to get it right. Strive to avoid this.

2. Establish ground rules with your clients about what kind of changes will be considered backward-compatible: what kind of changes they are expected to tolerate. For example, adding new fields to existing structures is something that clients should tolerate from the service. Pay careful attention to enumerations, sum types, and exceptions.

3. Version upgrades are expensive. Upgrading from one API version to another typically requires engineering time from every single client application. Any time that clients spend on version upgrades is time taken away from more useful activities. The total cost of a version upgrade grows in proportion to the number of clients. Don't gratuitously release new API major versions; strive to minimize them.

4. As a service provider, it often seems convenient to just release a new API version rather than put in the hard work to provide a feature in a backward-compatible way. (I see this more often in libraries than in services, where it's difficult to know 100% for sure that your change to the library won't break anyone.) Resist this temptation. Just because the upgrade costs your clients pay are hidden from you doesn't mean they don't exist. Version upgrades are disruptive and frustrating.

5. It's sometimes possible to implement backwards-incompatible changes through a series of smaller backwards-compatible or non-disruptive changes. For example, say that you want to rename an API element -- normally this would be a backward-incompatible change. However, you can break the change up into multiple steps: first, add the new element with the desired name and announce that the old name is deprecated. Next, work with your clients to upgrade them all to the new name. Once clients have migrated, you can remove the old name without impact. (How hard this is and how long it takes depends on the situation; it varies from relatively easy to almost impossible. A key factor is your clients - the more you can coordinate with and influence your clients, the easier this is.)

6. Releasing changes in backward-compatible or non-impacting ways is especially useful because it reduces the need for a service provider and client to directly coordinate. The service provider can announce a feature or change and clients can update to account for it on their own timeline. The service provider can then implement any backward-incompatible steps once all clients are ready.

7. When running any kind of migration, such as renaming an element or moving clients from one major version to another, it's helpful to have statistics about what people are using. If your V1 API isn't getting any traffic because users have moved to V2, or alternatively if it's continuing to receive traffic, then that's important to know if you're planning to deprecate it.

8. Versioning can usually be added after-the-fact if it's needed. It's often not necessary to worry about it too much up-front. I have yet to run into a situation where the lack of a version field caused a problem (because its absence can be interpreted as Version=1).

9. Most of what I said above matters when you have a large number of clients, or when you have clients that are outside your influence. This is big company, big-usage thinking. If you're e.g. a small company building services for your own consumption, don't worry about API versioning until you begin to notice friction. Instead, focus on making changes in backwards-compatible ways. If you need to make a backward-incompatible change, then talk to the people whose software will be affected. There might be an easier way to manage the change than maintaining two parallel API versions.

Re:How to Version an API by Moru on Friday June 09, 2017 @01:38AM (#14519371)
We had just changed to a new company running our invoices. They were still developing their API and we wrote code to transfer our invoices to them for printing and distributing. They were expensive and there was starting to pop up new competition for them. But we had already working code with them so we could not justify the cost of rewriting it. Suddenly they deprecated the old API forcing us to rewrite. Or liberated us to change to a cheaper and better alternative.

Well, we took the opportunity to change provider and are very happy now :-)

Re:How to Version an API by boriselec on Friday June 09, 2017 @07:54AM (#14520748)
Great points. Also make version tag explicit on both request and response.
Re:How to Version an API by and0 on Friday June 09, 2017 @10:31AM (#14521616)
Has anyone ever designed an API with subversioning on single calls?

So you'd have: service.com/api/v1/do_thing/v2/param

That way, you wouldn't have to try to snap new features to entire numbered revisions,and could open new parameters / results up to clients who are interested in the meantime. Seems like it would be the best of both worlds, but I've never had to design a serious API.

Re:How to Version an API by taormina on Thursday June 08, 2017 @03:49PM (#14516679)
At my last job, we used https://retailmenot.github.io/shield/ to both handle versioning and our microservices. This lets you even entirely swap out the microservice between versions!
Re:How to Version an API by iask on Friday June 09, 2017 @06:50AM (#14520496)
I go by this - breaking changes require versioning. And once I version, there is no time spent on backward compatibility. Time is money.
Re:How to Version an API by cdevs on Thursday June 08, 2017 @11:27PM (#14518982)
We do this at my job, what better way to screw over API users than to make them rewrite their integration every 2 years
Re:How to Version an API by novaleaf on Friday June 09, 2017 @11:43AM (#14522166)
article doesn't include "module", which I think is a big mistake, as it assumes a monolithic api for the entire business.

My opinion for a better structure:

domain.tld/api/module/version/

Re:How to Version an API by m42 on Thursday June 08, 2017 @03:27PM (#14516506)
graphql
Re:How to Version an API by dsp1234 on Thursday June 08, 2017 @04:46PM (#14517066)
https://developers.facebook.com/docs/graph-api

"The Graph API has multiple versions available"