[Novex]

Version Free sounds amazing - I can see the pros of being able to add/deprecate fields at the same API endpoint, but I find most of the reason we version our API is for field type changes as the data schema naturally evolves. We need to keep track of finer grained data in existing fields that wasn't originally thought of.

To take the Star Wars example at https://github.com/facebook/graphql and build on it. Let's say after this is deployed we need to expose a Planet's population as well. Now homePlanet goes from being a String to a Planet { name population } object.

This type change would break existing clients - the only real solution I can think of is introducing the planet object as PlanetDetails (essentially PlanetV2) and deprecating planet, but that's just back to versioning.

I feel like there must be a better way to deal with it? Interestingly, the graphql format allows this to be differentiated (as the old API won't request an object), but there appears to be no provision to union two non-objects into a single field?

[xxbondsxx]

Sure there are strong similarities to versioning, but I think the difference is in how callers get migrated. In GraphQL you can update each callsite incrementally. Imagine half the app has been converted to calling PlanetDetails {name} and the other half still calls homePlanet. That's totally fine -- the app will totally work, compile, run, everything.

Whereas contrasting with REST versioning or traditional versioning, it becomes quite difficult to mix API versions internally (each callsite needs to specify their desired api version before specifying fields) or impossible outright. If the latter, you're then forced to migrate all at once from a given version to another, which requires a ton of coordination across teams and big scary "flip the switch" moments.

This gets worse as you scale up your org, which is why GraphQL has served FB well.

[Jweb_Guru]

The most interesting work on this subject that I've read is probably FQL's approach: http://categoricaldata.net/fql/tutorial.pdf#subsection.2.3

It's totally unclear to me that GraphQL solves data migration problems.

[dschafer]

Yeah, introducing a new field and deprecating the old one seems like the best option here. The nice thing is that while this introduces new functionality, there's still only one version of the server; if you query for `homePlanet`, you always get the name, if you query for `homePlanetDetails`, you always get the planet object. This is particularly useful for tooling, since the API response is a function only of the access token and the query.