Every Gadget project comes with a rich, autogenerated GraphQL API that you use to query and mutate data stored in Gadget. However, interacting with a raw GraphQL API can be burdensome. You need to implement authentication, data hydration, pagination and, for TypeScript users, type generation.
Your client will
Once I have my client, I’ll instantiate it and start making API calls:
Like GraphQL, the generated client supports dynamic selections of different properties when querying data. For example, let’s say that our Post model Belongs To an Author model in our blog. if you want to select the blog post’s id, the post title, and author’s name of each post, you can use the <inline-code>select<inline-code> option:
This query will return just the fields you selected, just like GraphQL, ensuring minimal, fast communication between the server and the client.
Unlike most other clients, our selections are fully typed with TypeScript! If you’re using an editor that supports TypeScript, your editor will know what fields are present on the returned records, and can warn you if your properties aren’t part of the selection :
The <inline-code>select<inline-code> option is typed, preventing you from selecting fields that don’t exist:
As a developer using Gadget, you no longer need to configure a code generator or build step to get this type safety. Your API client package has these types built in, ready to use, just like that.
The API client library for your application has one job: hide the accidental complexity of communication so that you can spend your time on what really matters. In order to make it easy to use, we’ve made Gadget’s client feel just like any other SaaS platform’s API client -- familiar, because it uses the nouns and verbs of the domain and helpful, because it knows what inputs are valid and invalid for each specific API call.
This is a bit trickier for Gadget because we don’t have 5 hardcoded models we can write specific APIs and TypeScript types for -- you defined your own models! So, in your API client, the names of the functions and the groupings are not static, they’re derived from your models and actions. Same with the types: valid inputs and outputs are different for each model.
One option would have been to build a generic client without types that treat each bit of dynamism as a parameter. Something like:
You deserve better. Taking inspiration from the code generators before us like Prisma and graphql-code-generator, your Gadget API client now looks like this:
This is a big decision because it means that instead of publishing one universal API client library to npm, Gadget generates and hosts an api clients for each application powered by Gadget.
We want you to install this package the same way you install all others, via an npm registry,so we built out a dynamic one! When you <inline-code>npm install<inline-code> your Gadget client, the npm client makes a request to our registry at <inline-code>registry.gadget.dev<inline-code>, and we generate an up to date version of your API client. We store this package under a stable version ensuring you always install the same package with the same version. Over time, as your version changes the package evolves to match your backend application. Updating your API client works just like any other package update -- you bump the version in package.json or have a tool do it for you.