Extend Versioning paragraph in Best Practises

[benben]

The Versioning in the Best Practises section is explaining why traditional REST APIs need Versioning to deal with breaking changes. But later sentences don't explain what are the best practises with GraphQL do deal with breaking changes. For example how should I handle the case when I want to remove or rename a field of a type?

[j0k3r]

As far as I understand best practices are to keep your old field and add the new one.
Then you flag this old field as deprecated (isDeprecated) in your schema.

https://facebook.github.io/graphql/#sec-Object-Field-deprecation

But yeah I agree that a dedicated section about versioning could be a good idea.

[benben]

Thansk for your reply. I just saw that Facebook is still versioning their GraphQL API in the URI. Two other questions: How do you deprecate a whole type? How do you deal with mutations?

[stubailo]

I just saw that Facebook is still versioning their GraphQL API in the URI.

Are they? I haven't heard anything about this, as far as I know they've been using the same schema since the beginning. If anything, I suspect this is because they have rewritten the entire syntax and so they would need a separate endpoint for the old query language.

How do you deprecate a whole type? How do you deal with mutations?

I imagine you would deprecate all fields that point to that type. And you can deprecate mutations the same way, since they are just normal fields.

[benben]

@stubailo See here https://developers.facebook.com/docs/graph-api/overview/#versions

[stubailo]

The Graph API is not the same thing as GraphQL, even though they have similar names. Facebook doesn't have a public GraphQL API at all.

[stubailo]

The need for a versioning page is already recorded in the new site plan: #41

Going to close this issue then.

[benben]

The Graph API is not the same thing as GraphQL, even though they have similar names. Facebook > doesn't have a public GraphQL API at all.

Ah right, then I messed it up a bit 😊
Thanks for clarifying and working on it!