Graphql-engine: API versioning or adding support for deprecating parts of the GraphQL schema

[lidorcg]

Hello, first of all I want to say that your project is amazing, it's incredebly well-designed and moving at the speed of light!

Now I would like to raise a subject that is extremely important and extremely not trivial to handle: API versioning.

I haven't seen any discussions about the subject when I looked around the documentation and the issues section. So if there really isn't a discussion, I'd like to start one.

The issue is as followed:
Let's say you have some tables and people are interacting with the API hasura serves over these tables, and one morning you woke up with an incredible idea for a new naming system that is much more readable and simplify the interaction with your API.
Now, in an ideal world you would create a new API for your underlying tables, mark your old API as deprecated and give your clients some time to update thier code.

However with hasura we've made a tradeoff, in hasura the tables=API, to change the API we need to change the tables, it's easier and faster to develop but we've lost that layer of abstraction.

There are similar projects (like subzero) that offers a way to keep that layer of abstraction by providing an API schema which exports the other schemas via functions and views. This however, IMO, is just having a backend written in SQL so I'm extremely against that, the main value of projects like hasura is to make developing faster by obsoleting the backend.

And so, with no meaningful insights I'd like to start this discussion about API versioning on hasura with hope that someone more creative than myself will suggest the breakthrough I'm looking for.

Good luck to us all 😊

[LDesirest]

Hello ! I was asking myself the same question.

I think using schema is the way to go and I don't understand why you think "having a backend in SQL" is a bad thing, Hasura is built exactly for that, or I am missing something ? For me Hasura is really not about "obsoleting backend", you'll always need a backend. But more having a single source of truth, your SQL schema describe you API (and "build" the API from it). So instead of spending time building the API exposure and all, you just spend time on your data types and relationships.
For me the main issue is having schema as a prefix in your queries and not in URL. I'd be perfectly fine if I could do:
https://hasura.end.point/v1/graphql/myschema_v1
https://hasura.end.point/v1/graphql/myschema_v2

[andycmaj]

isn't the question, "how does myschema_v1 work given than v2 has caused permanent changes to the backing database schema"?

maybe as you create hasura migrations, you also must create corresponding graphql resolvers that tell v1 how to resolve it's data given v2 database schema?

[Bessonov]

Not hasura user yet, but highly interested in topic of versioning. I think you can achieve part of renaming without breaking changes with computed fields. But yes, this doesn't answer more general question stated above:

how does myschema_v1 work given than v2 has caused permanent changes to the backing database schema

I think a custom resolver / remote joins can help there, if a transformation from v2 to v1 is possible. For example, if you have

interface User { // v1
  full_name: string
}

and want to make it:

interface User { // v2
  firstname: string
  lastname: string
}

you probably can:

1. Create a migration to split full_name into firstname and lastname. With this you get User v2.
2. Create a custom resolver with full_name which use User v2 to query/mutate User data and follows same rule as migration did. This is a compatibility layer for User v1.

The one pity part is, with hasura you can't use deprecated on full_name.

Do I missing something? I can image that to support older clients could be a very complex task specially with hasura in comparison to apollo or RESTlike APIs, because it seems like the GraphQL interface is very tight to data base model (which has also benefits!).

[zlanich]

I too am interested in support for marking fields as deprecated, and in particular, the ability to use Apollo CLI to generate Typescript types with some sort of usable deprecated (JSDoc?) warning so my IDE can tell me if I'm using a deprecated field anywhere. I'm not seeing a way to do this yet, but I've seen many people wanting it. Does anyone have any insight on future support for type of thing, or any alternative way to achieve this?

Thanks!