GraphQL

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Jun 2, 2023

7 min read

Introducing the new Serverless, GraphQL, Apollo Server, and Contentful Starter kit

The team at This Dot Labs has released a brand new starter kit which includes the Serverless Framework, GraphQL, Apollo Server and Contentful configured and ready to go. This article will walk through how to set up the new kit, the key technologies used, and reasons why you would consider using this kit.

How to get started setting up the kit
How to Create the Technology Model in Contentful
How to seed the database with demo data
How to work with the migration scripts
Technologies included in this starter kit
Why use the Jest testing framework?
Project structure
How to deploy your application
What can this starter kit be used for?
Conclusion

How to get started setting up the kit

Generate the project

In the command line, you will need to start the starter.dev CLI by running the npx @this-dot/create-starter command. You can then select the Serverless Framework, Apollo Server, and Contentful CMS kit and name your new project. Then you will need to cd into your new project directory and install the dependencies using the tool of your choice (npm, yarn, or pnpm). Next, you will need to Run cp .env.example .env to copy the contents of the .env.example file into the .env file.

Setup Contentful access

You will first need to create an account on Contentful, if you don't have one already. Once you are logged in, you will need to create a new space. From there, go to Settings -> API keys and click on the Content Management Tokens tab. Next, click on the Generate personal token button and give your token a name. Copy your new Personal Access Token, and add it to the CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN variable. Then, go to Settings -> General settings to get the CONTENTFUL_SPACE_ID. The last step is to add those CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN and CONTENTFUL_SPACE_ID values to your .env file.

Setting up Docker

You will first need to install Docker Desktop if you don't have it installed already. Once installed, you can start up the Docker container with the npm run infrastructure:up command.

Starting the local server

While the Docker container is running, open up a new tab in the terminal and run npm run dev to start the development server. Open your browser to http://localhost:3000/dev/graphql to open up Apollo server.

How to Create the Technology Model in Contentful

To get started with the example model, you will first need to create the model in Contentful.

Log into your Contentful account
Click on the Content Model tab
Click on the Design your Content Modal button if this is your first modal
Create a new model called Technology
Add three new text fields called displayName, description and url
Save your new model

How to seed the database with demo data

This starter kit comes with a seeding script that pre-populates data for the Technology Content type.

In the command line, run npm run db:seed which will add three new data entries into Contentful.

If you want to see the results from seeding the database, you can execute a small GraphQL query using Apollo server.

First, make sure Docker, and the local server(npm run dev) are running, and then navigate to http://localhost:3000/dev/graphql.

Add the following query:

query TechnologyQuery {
  technologies {
    description
    displayName
    url
  }
}

When you run the query, you should see the following output.

{
  "data": {
    "technologies": [
      {
        "description": "GraphQL provides a strong-typing system to better understand and utilize our API to retrieve and interact with our data.",
        "displayName": "GraphQL",
        "url": "https://graphql.framework.dev/"
      },
      {
        "description": "Node.js® is an open-source, cross-platform JavaScript runtime environment.",
        "displayName": "Node.js",
        "url": "https://nodejs.framework.dev/"
      },
      {
        "description": "Express is a minimal and flexible Node.js web application framework.",
        "displayName": "Express",
        "url": "https://www.npmjs.com/package/express"
      }
    ]
  }
}

How to work with the migration scripts

Migrations are a way to make changes to your content models and entries. This starter kit comes with a couple of migration scripts that you can study and run to make changes to the demo Technology model. These migration scripts are located in the scripts/migration directory.

To get started, you will need to first install the contentful-cli.

   npm i -g contentful-cli

You can then login to Contentful using the contentful-cli.

   contentful login

You will then need to choose the Contentful space where the Technology model is located.

   contentful space use

If you want to modify the existing demo content type, you can run the second migration script from the starter kit.

   contentful space migration scripts/migrations/02-edit-technology-contentType.js -y

If you want to build out more content models using the CLI, you can study the example code in the /scripts/migrations/01-create-technology-contentType.js file. From there, you can create a new migration file, and run the above contentful space migration command.

If you want to learn more about migration in Contentful, then please check out the documentation.

Technologies included in this starter kit

Why use GraphQL?

GraphQL is a query language for your API and it makes it easy to query all of the data you need in a single request. This starter kit uses GraphQL to query the data from our Contentful space.

Why use Contentful?

Contentful is a headless CMS that makes it easy to create and manage structured data. We have integrated Contentful into this starter kit to make it easy for you to create new entries in the database.

Why use Amazon Simple Queue Service (SQS)?

Amazon Simple Queue Service (SQS) is a queuing service that allows you to decouple your components and process and store messages in a scalable way.

In this starter kit, an SQS message is sent by the APIGatewayProxyHandler using the sendMessage function, which is then stored in a queue called DemoJobQueue. The SQS handler sqs-handler polls this queue, and processes any message received.

import { APIGatewayProxyHandler } from "aws-lambda";
import { sendMessage } from "../utils/sqs";

export const handler: APIGatewayProxyHandler = async (event) => {
  const body = JSON.parse(event.body || "{}");
  const resp = await sendMessage({
    id: Math.ceil(Math.random() * 100),
    message: body.message,
  });

  return {
    statusCode: resp.success ? 200 : 400,
    body: JSON.stringify(resp.data),
  };
};

Why use Apollo Server?

Apollo Server is a production-ready GraphQL server that works with any GraphQL client, and data source. When you run npm run dev and open the browser to http://localhost:3000/dev/graphql, you will be able to start querying your Contentful data in no time.

Why use the Serverless Framework?

The Serverless Framework is used to help auto-scale your application by using AWS Lambda functions. In the starter kit, you will find a serverless.yml file, which acts as a configuration for the CLI and allows you to deploy your code to your chosen provider.

This starter kit also includes the following plugins:

serverless-offline - allows us to deploy our application locally to speed up development cycles.
serverless-plugin-typescript - allows the use of TypeScript with zero-config.
serverless-dotenv-plugin - preloads function environment variables into the Serverless Framework.

Why use Redis?

Redis is an open-source in-memory data store that stores data in the server memory. This starter kit uses Redis to cache the data to reduce the API response times and rate limiting. When you make a new request, those new requests will be retrieved from the Redis cache.

Why use the Jest testing framework?

Jest is a popular testing framework that works well for creating unit tests.

You can see some example test files under the src/schema/technology directory. You can use the npm run test command to run all of the tests.

Project structure

Inside the src directory, you will find the following structure:

.
├── generated
│   └── graphql.ts
├── handlers
│   ├── graphql.ts
│   ├── healthcheck.spec.ts
│   ├── healthcheck.ts
│   ├── sqs-generate-job.spec.ts
│   ├── sqs-generate-job.ts
│   ├── sqs-handler.spec.ts
│   └── sqs-handler.ts
├── models
│   └── Technology
│       ├── create.spec.ts
│       ├── create.ts
│       ├── getAll.spec.ts
│       ├── getAll.ts
│       ├── getById.spec.ts
│       ├── getById.ts
│       ├── index.ts
│       ├── TechnologyModel.spec.ts
│       └── TechnologyModel.ts
├── schema
│   ├── technology
│   │   ├── index.ts
│   │   ├── technology.resolver.spec.ts
│   │   ├── technology.resolvers.ts
│   │   └── technology.typedefs.ts
│   └── index.ts
└── utils
    ├── contentful
    │   ├── contentful-healthcheck.spec.ts
    │   ├── contentful-healthcheck.ts
    │   ├── contentful.spec.ts
    │   ├── contentful.ts
    │   └── index.ts
    ├── redis
    │   ├── index.ts
    │   ├── redis-healthcheck.spec.ts
    │   ├── redis-healthcheck.ts
    │   ├── redis.spec.ts
    │   └── redis.ts
    ├── sqs
    │   ├── client.spec.ts
    │   ├── client.ts
    │   ├── getQueueUrl.spec.ts
    │   ├── getQueueUrl.ts
    │   ├── index.ts
    │   ├── is-offline.spec.ts
    │   ├── is-offline.ts
    │   ├── sendMessage.spec.ts
    │   └── sendMessage.ts
    └── test
        └── mocks
            ├── contentful
            │   ├── entry.ts
            │   └── index.ts
            ├── aws-lambda-handler-context.ts
            ├── graphql.ts
            ├── index.ts
            └── sqs-record.ts

This given structure makes it easy to find all of the code and tests related to that specific component. This structure also follows the single responsibility principle which means that each file has a single purpose.

How to deploy your application

The Serverless Framework needs access to your cloud provider account so that it can create and manage resources on your behalf. You can follow the guide to get started.

Steps to get started:

Sign up for an AWS account
Create an IAM User and Access Key

Export your AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY credentials.

   export AWS_ACCESS_KEY_ID=<your-key-here>
   export AWS_SECRET_ACCESS_KEY=<your-secret-key-here>

Deploy your application on AWS Lambda:
```
   npm run deploy
```

To deploy a single function, run:

   npm run deploy function --function myFunction

To stop your Serverless application, run:

   serverless remove

For more information on Serverless deployment, check out this article.

What can this starter kit be used for?

This starter kit is very versatile, and can be used with a front-end application for a variety of situations.

Here are some examples:

personal developer blog
small e-commerce application

Conclusion

In this article, we looked at how we can get started using the Serverless, GraphQL, Apollo Server, and Contentful Starter kit. We also looked at the different technologies used in the kit, and why they were chosen. Lastly, we looked at how to deploy our application using AWS.

I hope you enjoy working with our new starter kit!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Jessica Wilkins

Jessica Wilkins is a classical musician turned Software Engineer. Prior to joining the tech industry, she spent her time running her own sheet music company (JDW Sheet Music) as well as performing and teaching in Los Angeles, CA. She enjoys working with React and TypeScript. She is also a prolific technical writer for freeCodeCamp.

@codergirl1991 @jdwilkin4

How to Resolve Nested Queries in Apollo Server

When working with relational data, there will be times when you will need to access information within nested queries. But how would this work within the context of Apollo Server? In this article, we will take a look at a few code examples that explore different solutions on how to resolve nested queries in Apollo Server. I have included all code examples in CodeSandbox if you are interested in trying them out on your own. Prerequisites This article assumes that you have a basic knowledge of GraphQL terminology. Table of Contents - How to resolve nested queries: An approach using resolvers and the filter method - A refactored approach using Data Loaders and Data Sources - What are Data Loaders - How to setup a Data Source - Setting up our schemas and resolvers - Resolving nested queries when microservices are involved - Conclusion How to resolve nested queries: An approach using resolvers and the filter method In this first example, we are going to be working with two data structures called musicBrands and musicAccessories. musicBrands is a collection of entities consisting of id and name. musicAccessories is a collection of entities consisting of the product name, price, id and an associated brandId. You can think of the brandId as a foreign key that connects the two database tables. We also need to set up the schemas for the brands and accessories. ` The next step is to set up a resolver for our Query to return all of the music accessories. ` When we run the following query and start the server, we will see this JSON output: ` ` As you can see, we are getting back the value of null for the brands field. This is because we haven't set up that relationship yet in the resolvers. Inside our resolver, we are going to create another query for the MusicAccessories and have the value for the brands key be a filtered array of results for each brand. ` When we run the query, this will be the final result: ` ` This single query makes it easy to access the data we need on the client side as compared to the REST API approach. If this were a REST API, then we would be dealing with multiple API calls and a Promise.all which could get a little messy. You can find the entire code in this CodeSandbox example. A refactored approach using Data Loaders and Data Sources Even though our first approach does solve the issue of resolving nested queries, we still have an issue fetching the same data repeatedly. Let’s look at this example query: ` If we take a look at the results, we are making additional queries for the brand each time we request the information. This leads to the N+1 problem in our current implementation. We can solve this issue by using Data Loaders and Data Sources. What are Data Loaders Data Loaders are used to batch and cache fetch requests. This allows us to fetch the same data and work with cached results, and reduce the number of API calls we have to make. To learn more about Data Loaders in GraphQL, please read this helpful article. How to setup a Data Source In this example, we will be using the following packages: - apollo-datasource - apollo-server-caching - dataloader We first need to create a BrandAccessoryDataSource class which will simulate the fetching of our data. ` We will then set up a constructor with a custom Dataloader. ` Right below our constructor, we will set up the context and cache. ` We then want to set up the error handling and cache keys for both the accessories and brands. To learn more about how caching works with GraphQL, please read through this article. ` Next, we are going to set up an asynchronous function called get which takes in an id. The goal of this function is to first check if there is anything in the cached results and if so return those cached results. Otherwise, we will set that data to the cache and return it. We will set the ttl(Time to Live in cache) value to 15 seconds. ` Below the get function, we will create another asynchronous function called getByBrand which takes in a brand. This function will have a similar setup to the get function but will filter out the data by brand. ` Setting up our schemas and resolvers The last part of this refactored example includes modifying the resolvers. We first need to add an accessory key to our Query schema. ` Inside the resolver, we will add the accessories key with a value for the function that returns the data source we created earlier. ` We also need to refactor our Brand resolver to include the data source we set up earlier. ` Lastly, we need to modify our ApolloServer object to include the BrandAccessoryDataSource. ` Here is the entire CodeSandbox example. When the server starts up, click on the Query your server button and run the following query: ` Resolving nested queries when microservices are involved Microservices is a type of architecture that will split up your software into smaller independent services. All of these smaller services can interact with a single API data layer. In this case, this data layer would be GraphQL. The client will interact directly with this data layer, and will consume API data from a single entry point. You would similarly resolve your nested queries as before because, at the end of the day, there are just functions. But now, this single API layer will reduce the number of requests made by the client because only the data layer will be called. This simplifies the data fetching experience on the client side. Conclusion In this article, we looked at a few code examples that explored different solutions on how to resolve nested queries in Apollo Server. The first approach involved creating custom resolvers and then using the filter method to filter out music accessories by brand. We then refactored that example to use a custom DataLoader and Data Source to fix the "N+1 problem". Lastly, we briefly touched on how to approach this solution if microservices were involved. If you want to get started with Apollo Server and build your own nested queries and resolvers using these patterns, check out our serverless-apollo-contentful starter kit!...

May 17, 2023

6 mins

GraphQL

Leveraging GraphQL Scalars to Enhance Your Schema

Introduction GraphQL has revolutionized the way developers approach application data and API layers, gaining well-deserved momentum in the tech world. Yet, for all its prowess, there's room for enhancement, especially when it comes to its scalar types. By default, GraphQL offers a limited set of these primitives — Int, Float, String, Boolean, and ID — that underpin every schema. While these types serve most use cases, there are scenarios where they fall short, leading developers to yearn for more specificity in their schemas. Enter graphql-scalars, a library designed to bridge this gap. By supplementing GraphQL with a richer set of scalar types, this tool allows for greater precision and flexibility in data representation. In this post, we'll unpack the potential of enhanced Scalars, delve into the extended capabilities provided by graphql-scalars, and demonstrate its transformative power using an existing starter project. Prepare to redefine the boundaries of what your GraphQL schema can achieve. Benefits of Using Scalars GraphQL hinges on the concept of "types." Scalars, being the foundational units of GraphQL's type system, play a pivotal role. While the default Scalars — Int, Float, String, Boolean, and ID — serve many use cases, there's an evident need for more specialized types in intricate web development scenarios. 1. Precision: Using default Scalars can sometimes lack specificity. Consider representing a date or time in your application with a String; this might lead to ambiguities in format interpretation and potential inconsistencies. 2. Validation: Specialized scalar types introduce inherent validation. Instead of using a String for an email or a URL, for example, distinct types ensure the data meets expected formats at the query level itself. 3. Expressiveness: Advanced Scalars provide clearer intentions. They eliminate ambiguity inherent in generic types, making the schema more transparent and self-explanatory. Acknowledging the limitations of the default Scalars, tools like graphql-scalars have emerged. By broadening the range of available data types, graphql-scalars allows developers to describe their data with greater precision and nuance. Demonstrating Scalars in Action with Our Starter Project To truly grasp the transformative power of enhanced Scalars, seeing them in action is pivotal. For this, we'll leverage a popular starter kit: the Serverless framework with Apollo and Contentful. This kit elegantly blends the efficiency of serverless functions with the power of Apollo's GraphQL and Contentful's content management capabilities. Setting Up the Starter: 1. Initialize the Project: ` 2. When prompted, name your project enhance-with-graphql-scalars. ` 3. For a detailed setup, including integrating with Contentful and deploying your serverless functions, please follow the comprehensive guide provided in the starter kit here. 4. And we add the graphql-scalars package ` Enhancing with graphql-scalars: Dive into the technology.typedefs.ts file, which is the beating heart of our GraphQL type definitions for the project. Initially, these are the definitions we encounter: ` Our enhancement strategy is straightforward: * Convert the url field from a String to the URL scalar type, bolstering field validation to adhere strictly to the URL format. Post-integration of graphql-scalars, and with our adjustments, the revised type definition emerges as: ` To cap it off, we integrate the URL type definition along with its resolvers (sourced from graphql-scalars) in the schema/index.ts file: ` This facelift doesn't just refine our GraphQL schema but infuses it with innate validation, acting as a beacon for consistent and accurate data. Testing in the GraphQL Sandbox Time to witness our changes in action within the GraphQL sandbox. Ensure your local server is humming along nicely. Kick off with verifying the list query: ` Output: ` Success! Each url in our dataset adheres to the pristine URL format. Any deviation would've slapped us with a format error. Now, let's court danger. Attempt to update the url field with a _wonky_ format: ` As anticipated, the API throws up a validation roadblock: ` For the final act, re-run the initial query to reassure ourselves that the original dataset remains untarnished. Conclusion Enhancing your GraphQL schemas with custom scalars not only amplifies the robustness of your data structures but also streamlines validation and transformation processes. By setting foundational standards at the schema level, we ensure error-free, consistent, and meaningful data exchanges right from the start. The graphql-scalars library offers an array of scalars that address common challenges developers face. Beyond the URL scalar we explored, consider diving into other commonly used scalars such as: * DateTime: Represents date and time in the ISO 8601 format. * Email: Validates strings as email addresses. * PositiveInt: Ensures integer values are positive. * NonNegativeFloat: Guarantees float values are non-negative. As a potential next step, consider crafting your own custom scalars tailored to your project's specific requirements. Building a custom scalar not only offers unparalleled flexibility but also provides deeper insights into GraphQL's inner workings and its extensibility. Remember, while GraphQL is inherently powerful, the granular enhancements like scalars truly elevate the data-fetching experience for developers and users alike. Always evaluate your project's needs and lean into enhancements that bring the most value. To richer and more intuitive GraphQL schemas!...

Nov 8, 2023

4 mins

GraphQL

How to Handle Uploaded Images and Avoid Image Distortion

When you are working with images in your application, you might run into issues where the image's aspect ratio is different from the container's specified width and height. This could lead to images looking stretched and distorted. In this article, we will take a look at how to solve this problem by using the object-fit CSS property. A Look Into the Issue Using the "Let's Chat With" App Let's Chat With is an open source application that facilitates networking between attendees for virtual and in-person conferences. When users sign up for the app, they can join a conference and create a new profile with their name, image, and bio. When the team at This Dot Labs was testing the application, they noticed that some of the profile images were coming out distorted. The original uploaded source image did not have an aspect ratio of 1:1. A 1:1 aspect ratio refers to an image's width and height being the same. Since the image was not a square, it was not fitting well within the dimensions below. ` In order to fix this problem, the team decided to use the object-fit CSS property. What is the object-fit CSS property? The object-fit property is used to determine how an image or video should resize in order to fit inside its container. There are 5 main values you can use with the object-fit property. - object-fit: contain; - resizes the content to fit inside the container without cropping it - object-fit: cover; - ensures the all of the content covers the container and will crop if necessary - object-fit: fill; - fills the container with the content by stretching it and ignoring the aspect ratio. This could lead to image distortion. - object-fit: none; - does not resize the content which could lead to the content spilling out of the container - object-fit: scale-down; - scales larger content down to fit inside the container When the object-fit: cover; property was applied to the profile image in Let's Chat With, the image was no longer distorted. ` When Should You Consider Using the object-fit Property? There will be times where you will not be able to upload different sized images to fit different containers. You might be in a situation like Let's Chat With, where the user is uploading images to your application. In that case, you will need to apply a solution to ensure that the content appropriately resizes within the container without becoming distorted. Conclusion In this article, we learned about how to fix distorted uploaded images using the object-fit property. We examined the bug inside the Let's Chat With application and how that bug was solved using object-fit: cover;. We also talked about when you should consider using the object-fit property. If you want to check out the Let's Chat with app, you can signup here. If you are interested in contributing to the app, you can check out the GitHub repository....

Jul 28, 2023

3 mins

JavaScript

End-to-end type-safety with JSON Schema

End-to-end type-safety with JSON Schema I recently wrote an introduction to JSON Schema post. If you’re unfamiliar with it, check out the post, but TLDR: It’s a schema specification that can be used to define the input and output data for your JSON API. In my post, I highlight many fantastic benefits you can reap from defining schemas for your JSON API. One of the more interesting things you can achieve with your schemas is end-to-end type safety from your backend API to your client application(s). In this post, we will explore how this can be accomplished slightly deeper. Overview The basic idea of what we want to achieve is: * a JSON API server that validates input and output data using JSON Schema * The JSON Schema definitions that our API uses transformed into TypeScript types With those pieces in place, we can achieve type safety on our API server and the consuming client application. The server side is pretty straightforward if you’re using a server like Fastify with already enabled JSON Schema support. This post will focus on the concepts more than the actual implementation details though. Here’s a simple diagram illustrating the high-level concept: We can share the schema and type declaration between the client and server. In that case, we can make a request to an endpoint where we know its type and schema, and assuming the server validates the data against the schema before sending it back to the client, our client can be confident about the type of the response data. Marrying JSON Schema and TypeScript There are a couple of different ways to accomplish this: * Generating types from schema definitions using code generation tools * Creating TypeBox definitions that can infer TypeScript types and be compiled to JSON Schema I recommend considering both and figuring out which would better fit your application and workflows. Like anything else, each has its own set of trade-offs. In my experience, I’ve found TypeBox to be the most compelling if you want to go deep with this pattern. Code generation A couple of different packages are available for generating TS types from JSON Schema definitions. * https://github.com/bcherny/json-schema-to-typescript * https://github.com/vega/ts-json-schema-generator They are CLI tools that you can provide a glob path to where your schema files are located and will generate TS declaration files to a specified output path. You can set up an npm hook or a similar type of script that will generate types for your development environment. TypeBox TypeBox is a JSON Schema type builder. With this approach, instead of json files, we define schemas in code using the TypeBox API. The TypeBox definitions infer to TypeScript types directly, which eliminates the code generation step described above. Here’s a simple example from the documentation of a JSON Schema definition declared with TypeBox: ` This can then be inferred as a TypeScript type: ` Aside from schemas and types, TypeBox can do a lot more to help us on our type-safety journey. We will explore it a bit more in upcoming sections. Sharing schemas between client and server applications Sharing our JSON Schema between our server and client app is the main requirement for end-to-end type-safety. There are a couple of different ways to accomplish this, but the simplest would be to set up our codebase as a monorepo that contains both the server and client app. Some popular options for TypeScript monorepos are: PNPM, Turborepo, and NX. If a monorepo is not an option, you can publish your schema and types as a package that can be installed in both projects. However, this setup would require a lot more maintenance work. Ultimately, as long as you can import your schemas and types from the client and server app, you are in good shape. Server-to-client validation and type-safety For the sake of simplicity, let's focus on data flowing from the server to the client for now. Generally speaking, the concepts also apply in reverse, as long as your JSON API server validates your inputs and outputs. We’ll look at the most basic version of having strongly typed data on the client from a request to our server. Type-safe client requests In our server application, if we validate the /users endpoint with a shared schema - on the client side, when we make the request to the endpoint, we know that the response data is validated using the user schema. As long as we are confident of this fact, we can use the generated type from that schema as the return type on our client fetch call. Here’s some pseudocode: ` Our server endpoint would look something like this: ` You could get creative and build out a map that defines all of your endpoints, their metadata, and schemas, and use the map to define your server endpoints and create an API client. Transforming data over the wire Everything looks stellar, but we can still take our efforts a bit further. To this point, we are still limited to serialized JSON data. If we have a created_at field (number or ISO string) tied to our user, and we want it to be a Date object when we get a hold of it on the client side - additional work and consideration are required. There are some different strategies out there for deserializing JSON data. The great thing about having shared schemas between our client and server is that we can encode our type information in the schema without sending additional metadata from our server to the client. Using format to declare type data In my initial JSON Schema blog post, I touched on the format field of the specification. In our schema, if the actual type of our date is a string in ISO8601 format, we can declare our format to be "date-time". We can use this information on the client to transform the field into a proper Date object. ` Transforming serialized JSON Data This can be a little bit tricky; again, there are many ways to accomplish it. To demonstrate the concept, we’ll use TypeBox to define our schemas as discussed above. TypeBox provides a Transform type that you can use to declare, encode, and decode methods for your schema definition. ` It even provides helpers to statically generate the decoded and encoded types for your schema ` If you declare your decode and encode functions for your schemas, you can then use the TypeBox API to handle decoding the serialized values returned from your JSON API. Here’s what the concept looks like in practice fetching a user from our API: ` Nice. You could use a validation library like Zod to achieve a similar result but here we aren’t actually doing any validation on our client side. That happened on the server. We just know the types based on the schema since both ends share them. On the client, we are just transforming our serialized JSON into what we want it to be in our client application. Summary There are a lot of pieces in play to accomplish end-to-end type safety. With the help of JSON Schema and TypeBox though, it feels like light work for a semi-roll-your-own type of solution. Another great thing about it is that it’s flexible and based on pretty core concepts like a JSON API paired with a TypeScript-based client application. The number of benefits that you can reap from defining JSON Schemas for your APIs is really great. If you’re like me and wanna keep it simple by avoiding GraphQL or other similar tools, this is a great approach....

Apr 17, 2024

6 mins

JSONTypeScript

Introducing the New Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Introducing the new Serverless, GraphQL, Apollo Server, and Contentful Starter kit

Table of Contents

How to get started setting up the kit

Generate the project

Setup Contentful access

Setting up Docker

Starting the local server

How to Create the Technology Model in Contentful

How to seed the database with demo data

How to work with the migration scripts

Technologies included in this starter kit

Why use GraphQL?

Why use Contentful?

Why use Amazon Simple Queue Service (SQS)?

Why use Apollo Server?

Why use the Serverless Framework?

Why use Redis?

Why use the Jest testing framework?

Project structure

How to deploy your application

What can this starter kit be used for?

Conclusion

Jessica Wilkins

You might also like

How to Resolve Nested Queries in Apollo Server

Leveraging GraphQL Scalars to Enhance Your Schema

How to Handle Uploaded Images and Avoid Image Distortion

End-to-end type-safety with JSON Schema

You might also like

How to Resolve Nested Queries in Apollo Server

Leveraging GraphQL Scalars to Enhance Your Schema

How to Handle Uploaded Images and Avoid Image Distortion

End-to-end type-safety with JSON Schema