Video Summary and Transcription
This Talk discusses the benefits of using GraphQL to unify data sources, the flexibility of deploying APIs with GraphBase, and the ability to customize the GraphQL API using TypeScript. The GraphBase SDK allows developers to import auth, config, connector, and schema, providing full type safety and configuration options. TypeScript provides a helpful coding experience with hover-over hints and descriptions. The Talk also highlights the ability to extend the Stripe API using custom code and the ease of configuration with GraphBase and TypeScript.
1. Unifying Data Sources with GraphQL
Hey everyone, I'm Jamie. Today at TS Congress, I'll be discussing the topic of unifying data sources with GraphQL. Building a scalable and maintainable API involves considering various concerns and dealing with different APIs and SDKs. With the abundance of data sources, it can be time-consuming to integrate them all. However, the flexibility to create diverse applications using different data sources is a great benefit. The challenge lies in the lack of consistent documentation and the need to ensure data is available at the edge for optimal user experience.
Hey everyone, I'm Jamie. I'm really excited to be here today at TS Congress and I hope that you're all having a fantastic time. So far, there are so many amazing speakers and talks lined up. I'm really excited to check those out and catch up.
But obviously after this talk, we only have a few minutes together today really to go through some slides and a demo. So I think we should dive right into the topic that is unifying data sources with GraphQL.
Now if you're building an API, it doesn't matter if that API is REST or if that's GraphQL. It's pretty hard. Yes, it's easy to install a dependency, create some type definitions with GraphQL, and then create some resolvers and then deploy it. It's easy to do that. But there are so many other things to consider when building something scalable that you want to deploy to production, at the edge, hopefully, for your users to use and consume.
And this list that you see here is really only a small snapshot into some of the concerns that you have to kind of think about when building something scalable and maintainable in production. But I think the biggest problem today, it's a great benefit to have. But the biggest problem is that we have so many different data sources today that we all have to figure out how to use all of the APIs and SDKs. Well, they all differ as well. There's a different learning curve. There's different types of documentation. Some are more documented than others. Some take no time at all to get started and some take days to figure out. And because we're using so many of these services now to deliver our end products, well, it can often just be really time-consuming to do that.
I think the simplest to-do app that we all used to do and build when we first got started with something, I think in today's world, with all of these different data sources, I think there is so many different implementations of that now where maybe it's you create a to-do app that when you add a to-do, it sends you a notification via Slack or email or SMS. So there's three services. And then maybe it's when you add something or remove something or check something or uncheck something, maybe that goes on to find spots in your calendar that are free so you can actually find time to do these to-dos. So yeah, there are so many things to consider when building apps with all of these different data sources. And it's great that we've got this flexibility. But yeah, like I say, the downsides is some of these APIs have better documentation. Some of them don't. But the biggest thing, I think, with this is that all of the different services that we use today, they aren't really focused on where the data maybe lives because they know that they could just rely on someone using some caching or a static site generator or something. So most of these just deploy to a single region. But of course, if we want to use all of these different services, that data really should be at the edge closest to the user so that you can get the best experience when using your application that obviously you create using TypeScript.
2. Flexibility in API Deployment and Data Integration
We are on a mission to solve the lack of flexibility in deploying APIs to different regions. At GraphBase, we allow developers to connect to any type of database and extend their applications with additional data sources. With our unified GraphQL API, you have full type safety on both the back end and front end. We provide tools to make this process easy and efficient.
And I think all of these APIs, they're deployed to a single region. And obviously you can pay to maybe deploy it to other regions. But I think that's just something that we all should have the flexibility to do and configure on our own. Because there are so many services that don't give you that flexibility when you really want it. And maybe if you are to get that from a service provider, they may charge you a lot more to do that. So that's the one thing that we are on a mission to solve at GraphBase.
And we allow developers to connect to any type of database, maybe a warehouse or a commerce application like Shopify. If you have a product in Shopify that you want to extend with more products or reviews. You might want to get those reviews from a different API. Maybe you have some content in HiGraph or Contentful or Sanity that you want to add to these product pages. Well, we give you the ability to kind of add data sources, extend them and add your own custom code and do other things. So we're on a mission to do that, to create a single GraphQL API that you can bring different data sources in with and then your different front ends as well. And with all of this, you have full type safety on the back end, full type safety on the front end with that unified GraphQL API. And there's so many cool tools to do that.
3. GraphBase: Unified GraphQL API and Configuration
GraphBase provides a unified GraphQL API that allows you to bring your own Auth provider and configure user permissions. It also offers caching at the edge and generates TypeScript types for GraphQL queries and mutations. With a single GraphQL SDL configuration, you can add auth providers and specify rules for authenticated requests. GraphBase works with any fetch request and ensures full type safety from the back end to the front end.
And the other thing that GraphBase does is obviously it has this unified GraphQL API where all of these data sources live. And then on top of that, you can add things like Auth. So you can bring your own Auth provider like Click or Auth0 and then you can say, this user can update but can't delete, or they can read and not write. All of that can kind of be configured within the configuration. But the actual user management happens elsewhere. So you can bring your own users, essentially, to use the API and the connected databases as well.
And then on top of that, we obviously mentioned previously about kind of how important it is to have data readily available at the edge, close to the user. Well, we do that with caching at the edge as well. So that's baked in to all projects that you can take advantage of. Then when you deploy this to production, if you open a branch on GitHub, we'll automatically create you a preview URL that you're very used to. No doubt, with things like Vercel and Netlify, they give you that immutable URL that you can use. We do the same for GraphQL. We'll give you that new API endpoint so you don't have to think about, you know, figuring out how can I build that myself? That just comes for free, out of the box. We also have other products like search, and then analytics as well, so you can get full insights into what's going on with your project. And like I mentioned before, this works with anything that you're using today. Wherever you can make a fetch request, you can use Graphbase. But the important thing that I want to highlight is GraphQL and TypeScript, they work very well together because of the type system. A GraphQL-strong type system can be used with things like the GraphQL code generator to generate all of the TypeScript types for all of your GraphQL types, and maybe it's your GraphQL queries and mutations, and if they have inputs and arguments, some are required, some are optional. The code generator can create something in TypeScript that maps to that. So when you're using Graphbase and you're creating your own custom resolvers, you can use all of that code, all of that generated code to create something that's fully type safe from the back end to the front end, which I think is really powerful.
But the topic that I really want to cover today and show in the demo next is actually when we started to build Graphbase, we had a single GraphQL SDL as configuration. So on the left here, you can see there is a schema. Then we have this custom directive called auth that you would then configure all of your different auth providers with. So this OpenIDConnectProvider could be something like clerk, or it could be auth0 or something else. You can add that as an auth provider. And then you can specify a list of rules. We just have one rule here, which is allow private. But then that would add some rules to your backend to only allow authenticated requests. Then below that, we have this GraphQL tag, which is defining a namespace, the URL to the Shopify store or to the Contentful store. And then we have some headers as well.
4. Building with GraphBase SDK
Here, we've just got a custom Shopify header. If you use this with Shopify, if you use this with Contentful, you could obviously pass through different headers. The SDL that people had to use for so long didn't give developers any hints into what was going on with all of the different kind of configuration and options. So we built the graph based SDK, which allows you to import things like auth, config, connector, schema. And as you're typing, you can use TypeScript to its full advantage. Thanks to TypeScript, you get full type safety and can configure all the different kind of arguments when building GraphQL queries and resolvers within GraphBase. Let's jump into a demo using the GraphBase CLI to initialize a new project and use TypeScript as our config option.
Here, we've just got a custom Shopify header. If you use this with Shopify, if you use this with Contentful, you could obviously pass through different headers. And then those would go on when you make that kind of request to the different providers.
So, yeah, this is the SDL that people had to use for so long. And it's fantastic. I still use it today. I also use the new TypeScript configuration, but the SDL was really nice. But the thing that it didn't give developers was it didn't give you any hints into what was going on with all of the different kind of configuration and options. You didn't get any help from TypeScript or the code editor when you were configuring back ends with SDL. So that's why when we spoke to the community, we noticed that a lot of people were looking for a way to create something that was type safe.
So we built the graph based SDK. The team put together a proposal. We spoke to the community and they said, wow, this is great. How can I use this? So we started to build the SDK, which allows you to import things like auth, config, connector, schema. And then you can create models from that. You can then connect things. And as you're typing, you can use TypeScript to its full advantage to make sure that you're passing a string where a string should be invoked and integer, etc. And things like the headers API, we make sure that you can customize and specify the right kind of keys and values there. And no one's going to mess those up. So you get that full type safety, which we love as well. Thanks to TypeScript.
And I think the other thing when you're building GraphQL queries and resolvers that are custom to you. So you're building these within GraphBase, you can configure all of the different kind of arguments that those have. And if there is any optional fields, you can declare that inside of here. And TypeScript helps you generate that SDL automatically. But yeah, I want to jump into a demo now. Now we'll open our code editor. Imagine this was your frontend application and you wanted to create a backend for your frontend. You can use the GraphBase CLI to initialize a new project. And then, of course, we want to use TypeScript as our config option.
5. Customizing GraphQL API with TypeScript
I'm going to cheat a little bit. I'm going to invoke some steps that I created earlier, so we can update and change how this configuration looks. But as we explore this file, we can now see that we can hover over things and we can invoke things, and we get full help thanks to TypeScript with all of these, kind of, descriptions and options that are available inside of our code editor. So let's get started by creating a query here. We have some arguments that are optional. Now we'll go over to the file that we have, hello.ts. Here we have a TypeScript function. We can import SDKs and whatever inside of here, but this is TypeScript. We're able to create a TypeScript resolver that we'll later deploy to the edge. In this schema that we see here, this was all generated from that TypeScript config. So we didn't have to worry about writing GraphQL SDL. We were able to just use TypeScript and forget about that you need to know GraphQL to build a backend. If you don't, you can use TypeScript to build these backends. Let's execute a mutation here with GraphQL. We will RSVP to the event. We can pass along our name and our status here, which is an enum in GraphQL, and we can send different enum values if we want to. And then when we run that operation here, that will return the data to us. So that is basically a custom GraphQL query and mutation using TypeScript that was configured using TypeScript instead of our graph-based repo. Next, we can do things like connect things like Stripe using the open API connector. And then here, thanks to TypeScript, we know exactly what we need to pass, things like headers, what the key is, what the value can be, and the same with transforms as well. We can transform the schema to exclude certain fields and queries and mutations.
I'm going to cheat a little bit. I'm going to invoke some steps that I created earlier, so we can update and change how this configuration looks. But as we explore this file, we can now see that we can hover over things and we can invoke things, and we get full help thanks to TypeScript with all of these, kind of, descriptions and options that are available inside of our code editor.
So, we love this experience now, and we think that our developers do, too. They tell us they do. And we're really excited to kind of expand on this builder pattern of building our API.
So let's get started by creating a query here. We have some arguments that are optional. Now we'll go over to the file that we have, hello.ts. Here we have a TypeScript function. We can import SDKs and whatever inside of here, but this is TypeScript. We're able to create a TypeScript resolver that we'll later deploy to the edge. I think now, with this resolver, we should start the GraphQL server, and then if we head on over to the port 4,000, we can launch Pathfinder.
In this schema that we see here, this was all generated from that TypeScript config. So we didn't have to worry about writing GraphQL SDL. We were able to just use TypeScript and forget about that you need to know GraphQL to build a backend. If you don't, you can use TypeScript to build these backends.
So as we run the next step now, we can create another mutation to RSVP to an event, maybe something like this. Then we can define some things like enums and inputs and a mutation, and we have a file now that accepts some parameters. All of this that we have here is type-safe, so you can work with TypeScript and GraphBase to create these backends, and you don't have to wait until you start the server to run into errors. We'll tell you if there is something up before you get there. And as you can see, the schema for GraphQL has been updated automatically using that TypeScript config that was converted to create this GraphQL API that you can then use for your front end.
Let's execute a mutation here with GraphQL. We will RSVP to the event. We can pass along our name and our status here, which is an enum in GraphQL, and we can send different enum values if we want to. And then when we run that operation here, that will return the data to us. So that is basically a custom GraphQL query and mutation using TypeScript that was configured using TypeScript instead of our graph-based repo. Next, we can do things like connect things like Stripe using the open API connector. And then here, thanks to TypeScript, we know exactly what we need to pass, things like headers, what the key is, what the value can be, and the same with transforms as well. We can transform the schema to exclude certain fields and queries and mutations.
6. TypeScript Benefits and GraphQL Integration
Thanks to TypeScript, users can now get all the help they need directly in the code editor. With the OpenAPIConnector and the server running, the Stripe API is available in GraphQL without the need to learn GraphQL from a server point. GraphBase abstracts the complexity and handles tasks like passing headers and logging for you.
And again, thanks to TypeScript, we get all of this help. Before, when we use an SDL, none of our users could do that just inside the code editor alone. They were always having to go to the documentation to reference what they could and couldn't do. And that took up a lot of time, and people weren't deploying and building applications quicker. But I think now with TypeScript, they are. It's fantastic.
So, with that OpenAPIConnector added and with the server running, we get all of the Stripe API here in GraphQL thanks to the OpenAPI spec. We take that and transform that into GraphQL. And users of GraphBase that wanna build these backends don't have to worry about learning GraphQL really from a server point. We'll abstract all of that complexity for you. And things like passing headers here, we can see we forward from the client to the underlying service, this case it's Stripe, and we update that. And when you make a request from the front end, we'll just pass that right along to Stripe, which is cool. And there's things like logging so you can dive in and figure out exactly what's going on if things do go wrong, instead of your resolver.
7. Extending Stripe API with Gravatar Field
Let's extend the Stripe API by adding a Gravatar field using custom code in our resolver. With GraphBase and TypeScript, we can easily configure this extension using the SDK.
Next, let's extend the Stripe API. Here we have a Stripe customer, the Stripe customer is the type in GraphQL for the Stripe customer, but users don't have a Gravatar field. So I think we should add one. Here's some custom code inside of our resolver that is fetching the email from that Stripe customer, and then it's creating that Gravatar URL, and then it's just gonna return a string. So now with that running, if we go to Pathfinder and we close the headers tab, we should now be able to invoke that Gravatar field that didn't exist before. That doesn't exist with Stripe, but we've been able to extend the Stripe API with GraphBase using TypeScript. Now we can pass a different value in the arguments here, and we can get a different link to get a different image size. So that has been extending Stripe with GraphBase and with TypeScript, and all we really had to do was configure what that looked like using the SDK and then writing that code.
Comments