Raison D'souza

While that post about GraphQL is trending, here are my notes. I've worked on and helped with GraphQL implementations in Node, Ruby & Python, across micro-services. It's almost 2am. And I have a fckton of solutions, notes, opinions, whatever and in no particular order, all from memory. So I'll just type them here. Use "summary" types to limit query nesting. * For certain types with a lot of nested fields, some of these fields would return "shadow types" of the original type. These were basically types with some fields from the original type, without the fields that allowed further nesting. * There's also query length that can be used to limit queries. Lookup the queried fields to optimize data-fetching In one case, we used the parsed query structure in the python graphl lib to check the fields being queried and then fetch appropriate data to return. I very clearly remember working on @kann87's laptop one afternoon for this 😀 Errors You have to plan how you want your errors to be returned since multiple queries are possible. Very likely that the easy way is going to be responses & errors with status:200, because your errors could be only in parts if your query spans different actions. (we did more; notes in next section). Schema stitching * The v1(?) of Apollo server allowed piecing together multiple GraphQL endpoints into one endpoint. We wrote our own schema-stitching endpoint on top of Apollo server with some bells and whistles (below). * This included checking responses from different micro-services for errors and returning an appropriate status code. * The graphql introspection queries would have to be supported without authentication for end-users to be able to explore APIs with their graphql clients. Now when you add schema-stitching, it gets complicated. You now have to parse the query at the schema stitching endpoint to check if the query is an introspection query to be passed on as is, or if it has to be authenticated before passing it downstream to a micros-service. * We had a small implementation in here that translated certain REST calls to GraphQL. This was for some large customer that demanded a REST API because their only integration engineer knew "REST". * Authentication would ideally be here at the endpoint. That's what we did. But then I one fine day, someone up-top mandated that auth be it's own micro-service and so we had the n+1 with auth queries being made on each micro-service that was serving part of the query (This one - like many other things - is on me. I should have stood my ground to not let non-coding managers decide what happens in the codebase). * What about file uploads? We built support for that too with this schema-stitcher endpoint. Testing You can say bye bye to your "I'll call this endpoint with these params and get this response" tests. It now is combination of inputs/queries/mutations that need to be tested. I read somewhere that someone wanted to do property-based testing for graphql APIs. Versioning I remember seeing some popular company API using suffixes like "CreatePandaV2", and another using headers to version their APIs. How do you plan to version your APIs? And you also have to decide what types/queries are exposed in different versions. GraphQL is no guarantee that your frontends are going to make few queries. We can all dream 🤣 Frontends can have serious tech debt too and when they have it, you'll be disappointed to find your frontends making multiple API calls to populate different sections of the UI despite the graphql endpoint being able to serve them all at once. Requires re-thinking tooling * Integrations with observability tools won't be out of the box. Your request metrics for the endpoint are useless now. You have to switch to publishing measurements at the level/functions that respond to the GraphQL types/fields/queries. * Not just integration, reviewing these metrics becomes a hard task (and therefore makes it useless to have them). * If you have schema-stitching, depending on your setup, the endpoint has to be restarted every time there's an update to a micro-service deployed with a new/updated schema. Impact on API end-users outside the company * While it is possible to use apps to explore GraphQL schema, nothing beats documentation that users can Google. Without this, your team will have to write additional cookbook-style documentation, with the assumption that readers do not know GraphQL. * Exposing this API to customers impacts caching because unlike your frontend, these users can hit your API with any combination of fields. * Ok, also explain cursor-based pagination, graphql file uploads, etc, to customers 🤣 * Or try explaining to customers that are using the existing API that there's this new GraphQL API and... 🏃 What's one good thing that came of it? Better collaboration. When planning work, the frontend and backend engineers would decide the schema (queries, types, mutations, etc) and part ways until it was time to integrate and test. The graphql schema could be used to generate an endpoint with fake data (this setup is EASY with graphql). So the frontend folks could work in parallel. The folks would just switch the endpoint on the frontend from the fake data endpoint to a real one. I'm sure this is possible with non-graphql stuff too, but I haven't explored (maybe throw an OpenAPI spec and get fake data?). Would I do GraphQL again? Fuck no. I like my peace. I would rather go with purpose-built REST APIs than free-form query-what-you-want APIs like graphql. Your frontend requires a special API endpoint? Write one. This helps keep surface area smaller for bugs. For most of us, GraphQL is one of those things that reads impressive on a tech blog of a large company, but horrible if brought home. It may seem like GraphQL types/fields can just be thrown together as you grow your APIs, but designing GraphQL APIs requires thorough planning (much more than a usual HTTP API endpoint). Especially so, if you have end-users/customers using the APIs. Not all Engineering teams can afford the time. And some of us (especially me as I get older), don't want the headache of onboarding every new person with an additional paradigm/layer. While it may be old adage for some, this experience etched "keep it simple" on my mind permanently.