Most teams that want GraphQL already have a REST API. They cannot switch in a weekend, and they should not have to. So the realistic plan is: keep calling REST, and move to GraphQL as the server catches up. GraphLink 6.0 is built for that plan.

TL;DR

• Describe a REST endpoint in a schema file, run glink, and get a typed client in Dart, Java, TypeScript, Kotlin, Swift, Python or Go.
• Cache REST calls on the client with @glCache, using the same store and tags as GraphQL.
• Migrate a field to GraphQL by removing one directive. The call site does not change.

The problem

A hand-written REST client is a pile of small chores. A model class for every response. A serializer for every model. A function per endpoint that builds the path, the query string and the body, sends them, checks the status, and decodes the result. Then the same chores in the mobile app, the web app and the backend service, in three languages.

When the API later moves to GraphQL, all of that gets rewritten, because REST calls and GraphQL calls look nothing alike.

One schema file

GraphLink describes a REST endpoint with a directive on a field of Query or Mutation:

@glRestPrefix shares a path across a block, and each argument gets a role: here the id fills the {id} placeholder and @glRestBody is the JSON body. Other roles cover query strings, headers, form fields and multipart parts.

A schema with only REST operations needs no GraphQL URL and no GraphQL adapter. You do not need a GraphQL server to try this.

Using the generated code

Run glink, and the client has one method per field:

The same schema generates the equivalent in TypeScript, Kotlin, Java, Swift, Python and Go. A non-2xx status throws a RestError with the status, headers and body, so a server error is never silently turned into null.

A cache that is not an HTTP cache

Now the part that REST clients rarely have. Add the cache policy to the schema:

Within two minutes, a second product("p1") is answered from the client's store without a request. A successful createProduct evicts everything tagged products. The policy comes from your schema, not from Cache-Control headers, so it works even when the API sends none.

It is the same store and the same tag space that GraphQL operations use. A GraphQL mutation can invalidate a tag held by a REST query, and the reverse. That matters for the next step.

This is a per-operation cache with tags and an offline fallback ( staleIfOffline, for transport failures only). It is not a normalized entity cache.

What happens under the hood

The generated client never touches the network by itself. It builds a request (method, path, query, headers, body) and calls one function you provide, or a generated adapter for package:http, Dio, fetch, axios, OkHttp, URLSession, httpx or net/http. The response is decoded into the generated types. There is no runtime dependency on GraphLink.

Migrating, one field at a time

The day the GraphQL server can resolve product, remove the directive from that one field:

The type, the method and the call are the same. Only the transport changed. Every other field keeps working over REST until its turn, and the shared cache keeps @glCache and @glCacheInvalidate working while you move.

If today’s REST API omits fields that the schema declares non-null, mark the operation @glRestNullable. The client then decodes into a copy of the type ( ProductRest) where every field is nullable, so calls do not fail while the API catches up.

Limitations

• REST operations exist in the Dart, Java, TypeScript, Kotlin, Swift, Python and Go clients.
• Subscriptions are always GraphQL.
• Only GET queries are cached.
• If you used @glRestNullable, the result type goes back from ProductRest to Product when the field moves to GraphQL, with no automatic conversion.
• The cache is per operation and arguments, not normalized by entity.

Try it

• Why REST: https://graphlink.dev/why-rest.html
• REST operations reference: https://graphlink.dev/rest-client.html
• Install: https://graphlink.dev/getting-started.html

Originally published at https://graphlink.dev on November 10, 2026.

GraphLink 6.0 adds a Python and a Go client, serves REST operations through the same generated client in all seven languages, converts custom scalars with codecs, and fails loudly where it used to guess. Some of that is breaking, so the migration notes are at the end.

Seven clients

Dart, Java, Kotlin, TypeScript, Swift, Python and Go all generate from the same schema. The two new ones follow the idioms of their language:

• Python: pydantic v2 models, an asyncio client with keyword-only arguments, AsyncIterator subscriptions, and httpx and websockets adapters.
• Go: plain structs with json tags in one package, a context-aware client whose methods return (value, error), channel subscriptions, and net/http and coder/websocket adapters. Go 1.22 or later.

Both have caching with tag invalidation, file uploads, @glCaptureErrors and persisted queries.

REST operations

Annotate a field of Query or Mutation with @glRest and the generated client calls it over HTTP/JSON instead of GraphQL.

The call site is the same as for a GraphQL field. To move an API from REST to GraphQL one field at a time, remove the directive. Arguments get explicit roles (@glRestPath, @glRestParam, @glRestHeader, @glRestBody, @glRestField, @glRestPart), responses can be JSON, text, Void or a streamed Download, and @glCache works on REST operations too. @glRestNullable decodes into a copy of the response type where every field is nullable, for APIs that omit fields the schema declares non-null. See REST operations.

Scalar codecs

A typeMappings entry can now be an object, so a custom scalar is converted when it is decoded and encoded:

{} stands for the value. The codec applies to fields, list elements, input fields and operation arguments, and jsonType makes the generated decoder check the JSON type before your fromJson runs.

A stricter generator

• Directives are validated. Every directive must be built in or declared with directive @name ... on .... Unknown or misspelled arguments, wrong value kinds and wrong locations fail generation with the line and column. glink --print-directives prints the declarations of GraphLink's own directives for your IDE.
• Bad responses fail clearly. A response with no data and no errors, or a non-2xx status without a GraphQL body, now fails with the client's error type instead of returning null or crashing.
• Uploads stream in every client instead of being built in memory, with exact progress and chunked transfer when the length is unknown.

Migrating from 5.x

1. Declare your custom directives (federation’s @key, your own @auth) and fix the typos the new errors point to.
2. Regenerate and review the diff. Projected interface and union names, and the _all_fields fragments of types in a cycle, can change.
3. Swift: fromJson of every type that holds an interface or union is now throws; call it with try.
4. Java and Kotlin: DefaultGraphLinkClientAdapter takes a decoder. The GraphLinkClient factory methods are unchanged.
5. Python and Go: a missing non-null field is now an error that names the type and the field.

The full list is in the changelog.

Try it

Originally published at https://graphlink.dev on November 10, 2026.

GraphQL promises that you can ask for exactly what you want and no more. In the last video the generated client fetched every book together with its author. That is fine until you only need the books.

This post covers the next step: write your own query, let GraphLink generate the method for it, and see what the generated Dart looks like. The video shows all of it, and the sections below follow the same order.

Watch on YouTube

The query

The schema is still the bookstore from the quickstart: authors and books, where a Book has an author. We want the books without their authors. Create a second file next to the schema, queries.graphql:

The name is long on purpose. It comes from Java habits: it is verbose, but when you read it you know what you are going to get.

If you run glink now, nothing new appears in the client. The generator only knows about the files listed in the config, so add the query file next to the schema:

I forgot this step in the video and had to debug it, so it is worth remembering. Run the command again:

The generated method

The client now has a new method, next to the ones generated from the schema, with the same name as your query:

In the video this prints the first book’s title, The Dispossessed. Everything is typed: there is no map and no cast.

No dollar signs

Look at the generated names. There are no dollar signs in the functions or the types. Some GraphQL code generators add them, and I never understood why. GraphLink doesn’t, because if your app already talks to a GraphQL server you shouldn’t have to give up names like Author and Book for generated code. The names should be as natural as possible.

A class for the projection

Open the response and you will find a new class named after the type and the fields you picked: Book_IdTitleYear. It has id, title and year as final fields, a constructor with named required parameters, and its own toJson and fromJson.

Why a new class and not the existing Book? Because Book has an author, and the schema says it is never null. If the query didn't select it and GraphLink reused Book, the only honest choice would be to make every field nullable, and you would be checking for null on values you know are there. With a dedicated class, a field that isn't null in the schema is still not null in your code. That is also why this works for languages with null safety: Dart, Kotlin and TypeScript (TypeScript handles it a bit differently).

Try it

The rest of the Dart series covers fragments, batching, caching and subscriptions.

Originally published at https://graphlink.dev on November 2, 2026.

A GraphQL schema is fully typed. Then you write the Dart client by hand, and the types stop at the network boundary: Map<String, dynamic>, string keys, casts, and a query string you hope matches the server.

GraphLink skips that part. It reads your schema and writes the client for you, with models, inputs, queries and mutations, all typed and null-safe. This post is the quickstart: one schema, one command, and a first query against a real server. The video shows all of it, and the sections below follow the same order.

Watch on YouTube

The schema

The example is a small bookstore: authors and books, two queries and one mutation. It is deliberately simple.

One config file, one command

GraphLink needs a small config file that points at the schema and says where the output goes:

packageName has to match the name in your pubspec.yaml. Then you run the CLI:

In the video it reports 30 files generated in about 10 milliseconds. Installation instructions for glink are in the docs at graphlink.dev.

What you get

Under lib/generated there are a few folders ( client, enums, inputs, interfaces and types) and one file, graphlink.dart, which is the only thing you import.

Take the input type from the schema. The generated Dart class has typed fields, a constructor with named parameters, and toJson and fromJson. That means you don't need json_serializable, and you can remove it from your dependencies.

It is null-safe because the schema is. If you make a field optional in the schema, for example name on Author, run glink again and the Dart field and the constructor parameter become optional too. The compiler then points at every place in your code that needs to change.

Look at pubspec.yaml and you will find only http. GraphLink is not a dependency. It is a code generator, so the output is plain Dart, and if you delete GraphLink tomorrow your code still compiles.

The adapter and the first query

The generated client needs an adapter. An adapter is a function that takes the payload and returns a Future<String> with the server's response. That is the only way GraphLink talks to your server, so it doesn't care how the data travels. For HTTP, GraphLink generates one for you:

The query for book(id: ID!) has a required, named id parameter, and book.title and book.author.name are typed values, not map lookups. In the video the server is a small Spring Boot app, and fetching book 1 and then book 2 returns the right titles and IDs.

No magic

The last part of the video opens the generated query. The client declares the query and a map of fragments, one “all fields” fragment per type, and sends only the fragments the query needs. For Book that means its own fields plus the fragment for Author. All of it is ordinary Dart that you can read.

Try it

The rest of the Dart series covers custom queries, fragments, batching, caching and subscriptions.

Originally published at https://graphlink.dev on October 29, 2026.

GraphQL is a good deal on paper. You get a typed schema, one endpoint, and clients that ask for exactly the data they need. Then you write the client, and the typed schema stops at the network boundary.

This post walks through the six pains I kept running into when building GraphQL clients, and what happens to each of them when the client code is generated from the schema instead of written by hand. Each section links to a short video that shows it in action.

The idea: your schema is the source of truth

GraphLink is a compiler. You write your GraphQL schema once. GraphLink reads it and generates a typed, null-safe client in your language: Dart, Java, Kotlin, TypeScript or Swift.

Two things it is worth being clear about up front:

• It is a code generator, not a runtime library. The output is plain code in your language. Delete GraphLink tomorrow and your code still compiles.
• The schema is the only thing you maintain. Change the schema, run the generator again, and the compiler tells you what broke.

Watch the introduction: https://youtu.be/W3kYySbsz0k

Now the pains.

Pain 1: Raw maps and no compiler help

With a plain HTTP client, a GraphQL response is JSON. You decode it into a Map<String, dynamic> and dig out the values yourself:

Dart’s dynamic makes this look easy, which is part of the problem. Rename a field on the server and this still compiles. You find out when a user opens the screen. In Java or Kotlin you would also have to cast at every step, which is more code and the same risk.

With a client generated from the schema, the same call looks like this:

books is a list of Book. title is a String, year is an int, and book.author.name autocompletes. No casts, no maps, no string keys. Nullability from the schema carries through, so a field declared non-null is non-null in your code.

Watch: https://youtu.be/G2QVInjpA-A

Pain 2: Subscriptions

Subscriptions are the part of GraphQL that most clients make you build yourself. By hand it goes like this:

1. Open a WebSocket to the server.
2. Send a connection_init payload, with a bearer token if you need authentication.
3. Send the subscription itself.
4. Decode every raw message and branch on its type: connection_ack, ping (and reply with pong), next, error, complete.
5. Handle dropped connections and server restarts, with backoff and a reconnect that re-sends the init and subscribe messages.

That is a small protocol implementation, and it has to be right every time.

GraphLink generates this boilerplate for each subscription in your schema. In Dart you call a method on the generated subscriptions object and get a Stream back, then listen to it like any other stream. TypeScript works the same way. Java supports both reactive and blocking styles, and in the blocking one you pass a listener interface.

Watch: https://youtu.be/PuU7B25OJC8

Pain 3: Caching

Caching is meant to stop the client from asking the server for something it was just told. Doing it by hand has two traps:

• Partial responses overwrite complete ones. You fetch a book with its title and ISBN and cache it. Elsewhere in the app, another query fetches the same book with only the ISBN, and it replaces the fuller entry.
• The logic is yours to test. Cache keys, expiry, and invalidation after mutations all need tests, and mocks for those tests.

GraphLink moves caching into the schema, which stays the source of truth. You mark a query with @glCache, giving it a time to live and a set of tags. To clear entries before they expire, you mark a mutation with @glCacheInvalidate and the tags it should invalidate:

When addBook succeeds, the generated code evicts everything tagged books. The heavy lifting is generated. What you write is a couple of lines in the schema.

Watch: https://youtu.be/2Ojjk259hcI

Pain 4: Batching meets caching

Batching is a real GraphQL feature: ask for a book and an author in one query, in one HTTP request. The problem appears when you combine it with a cache. Most caches store the whole response as a single entry. Later, when you ask for only the book, the cache misses, even though the book is sitting right there inside the batched response.

GraphLink does not cache the whole response as one entry. It splits the response into separate entries. Here is the sequence from the video:

1. The app loads a book by ID. That is a miss, so the request goes to the server.
2. The app sends a batched request for the book and an author. The book comes from the cache, and only the author goes to the server.
3. A mutation adds a book, which evicts the book cache entries. The next batched request hits for the author and fetches only the book.

Each request sends only what the cache does not already have.

Watch: https://youtu.be/fVzvVfBl0IU

Pain 5: File uploads

A word of caution first: uploading files through GraphQL is not recommended in general. GraphQL is text-based, and a separate REST service for uploads is often the better design. But plenty of servers do accept uploads through GraphQL, so a client should handle it.

By hand, it means following the GraphQL multipart request convention. The variable that holds the file has to be null in the query payload. You add an operations part and a map part, both JSON, that describe which form field belongs to which variable. You read the file from the device, attach it, send the request, and then decode the response as raw data again.

In GraphLink you declare a custom scalar and mark it with @glUpload:

Any mutation that uses that scalar gets the multipart transport, and the generated client method takes a generated GLUpload type. In Java, for example, you create one from a File, a byte array, or an InputStream. The multipart request is generated for you.

Watch: https://youtu.be/u5Jbknx7R9g

Pain 6: Error handling

In GraphQL, an HTTP 200 does not mean success. A response can carry a normal status code and still contain a non-empty errors list, such as not authorized. A hand-written client has to check the status code, check the errors list, and do it consistently on every call. That is boilerplate that spreads through the code base.

GraphLink gives you two modes:

• Default: if the response contains errors, the call throws a GraphLink exception that carries the list of errors. Either the call worked or it threw.
• Capture mode: you mark a query or mutation with @glCaptureErrors, and the call returns the result with data and errors side by side instead of throwing. You check response.hasErrors yourself.

Capture mode earns its place with batched queries and partial failures. Suppose you ask for the list of books and the list of authors in one query, and you are allowed to see the books but not the authors. The server returns data with the books and a null for the authors, plus an errors entry explaining the authors failure. With capture mode, you keep the books and still see the error, instead of losing everything to an exception.

Watch: https://youtu.be/ySqkQ6ssSgk

Why I built it

I wanted to use GraphQL with a Flutter app. On the server side I liked how Spring Boot’s GraphQL support handled data: I did not need to write a lot of DTOs. On the client side I found an existing generator and was happy at first. Two things got in the way. It returned streams where I expected futures, and it produced names with dollar signs that I did not like.

The bigger issue was how it talked to the backend. At the time it sent the whole schema’s worth of definitions, including fragments that the query did not use. A Java GraphQL server rejects a query with unused fragments, so it failed against my backend. I am not naming the library. The authors did good work, and it may work well with other backends. It did not work with mine, and a Java server will refuse anything it considers unnecessary.

That is where one of GraphLink’s design rules comes from: send the minimum the backend needs. GraphLink decides which query is sent to the server.

Two other design points follow from that:

• Framework-agnostic transport. You provide the function that sends the request. In Dart that is a function that takes a string and returns a Future<String>. That makes it easy to mock in tests, and you do not need to test the generated code itself.
• Server scaffolding. GraphLink can also generate server code (Spring Boot and Express/Apollo), where you implement a few interfaces and the rest is done.

Watch the recap: https://youtu.be/W9MwmBmtIeA

Honest limits

• You still need a GraphQL server. GraphLink generates the client, and optional server scaffolding, not your business logic.
• Generated code is overwritten every time you run the generator. Keep your own code outside the generated folder.

Recap

One schema, typed and null-safe clients. Subscriptions, caching, batching, uploads and error handling are generated, not hand-written. Because the output is plain code, you can leave whenever you want.

Try it

• Full video playlist: https://youtube.com/playlist?list=PLQCBiENjF_uU
• YouTube channel: https://www.youtube.com/@Graphlinkdev
• Docs and quickstart: https://graphlink.dev
• GraphLink on GitHub: https://github.com/Oualitsen/graphlink (a star helps a lot)
• Code from the videos: https://github.com/Oualitsen/graphlink-demos
• Community on Reddit: https://www.reddit.com/r/graphlinkdotdev/
• Follow on X: https://x.com/graphlinkdev

If you hit a problem, open an issue on GitHub. Tell me which pain bites you the most, and I will cover it in the next video.

Originally published at https://graphlink.dev on October 25, 2026.