Lack of API Versioning and Error response in the documentation

It will be good if FaunaDB team provide some kind of API versioning for GraphQL endpoint (ex: https://graphql.fauna.com/graphql/v1, https://graphql.fauna.com/graphql/v2 etc) to make sure that the response stays the same and list of all possible error message. Especially for unique index.

Thanks.

In the meantime, until someone that knows more about this responds.
I am not the best reference for GraphQL. @lregnier, please correct me if I’m wrong.

My thoughts: from your other message regarding uniqueness you were matching on the ‘message’ of the uniqueness error. I would expect that it’s better to match on an error code and not the message. A message is meant to be clear to the user about what is going on and sometimes you need to revisit this to make it clearer. A code on the other hand should not change.

About versioning in general for the GraphQL endpoint. Currently the generated GraphQL API is versionless but you shouldn’t expect to see breaking changes though. It will most probably be versioned in the future though when significant changes are needed.

1 Like

@databrecht noted with thanks :pray:

To expand on @databrecht’s point, the GraphQL API is effectively a versionless API for the time being. We’re following what is also called a Continuous Evolution approach. In practice, all of this means that there is no API version parameter at all, and that any new changes are always introduced in an additive way (in other words, there should be no breaking changes at any time).

That being said, we might introduce versions in the future though. Those might be tied to a (wide) limited time frame support, which should allow users to upgrade to newer versions.

In any case, it might be fair to add at this least this brief explanation about versioning within our docs as well for future references.