Building a flexible API

Start from a DataBridge

Schemas serve as the single source of truth for your data shape. But what about API shape?

You can combine input and output schemas into a bridge file to serve as the single source of truth for your API resolver. You can use createDataBridge to ensure all the required fields are present:

import { Post } from '../schemas/Post.schema'
import { createDataBridge } from '@green-stack/schemas/createDataBridge'
 
/* -- Bridge ------------- */
 
export const updatePostBridge = createDataBridge({
    // Assign schemas
    inputSchema: Post.partial(), // You can create, reuse or extend schemas here if needed
    outputSchema: Post,
 
    // Used for GraphQL defs
    resolverName: 'updatePost',
    resolverArgsName: 'PostInput',
 
    // API config
    apiPath: '/api/posts/[slug]/update',
    allowedMethods: ['POST', 'GRAPHQL'],
})

Don’t worry too much about the GraphQL and API route config for now. We’ll get to that soon.

Think of a “Databridge” as a literal bridge between the front and back-end.

It’s a metadata object you can use from either side to provide / transform / extract:

• ✅ Route handler args from request params / body
• ✅ Input and output types + validation + defaults
• ✅ GraphQL schema definitions for schema.graphql
• ✅ The query string to call our GraphQL API with

There’s two reasons we suggest you define this “DataBridge” in a separate file:

• 1. Reusability: If kept separate from business logic, you can reuse it in both front and back-end code.
• 2. Consistency: Predicatable patterns make it easier to build automations and generators around them.

For this reason, we suggest you add .bridge.ts to your bridge filenames.

Add your business logic

Let’s use the data bridge we just created to bundle together the input and output types with our business logic.

You can do so by creating a new resolver file and passing the bridge as the final arg to createResolver at the end. The first argument is your resolver function containing your business logic:

import { createResolver } from '@green-stack/schemas/createResolver'
import { updatePostBridge } from './updatePost.bridge'
import { Posts } from '@db/models'
 
/** --- updatePost() ---- */
/** -i- Update a specific post. */
export const updatePost = createResolver(async ({
    args, // <- Auto inferred types (from 'inputSchema')
    context, // <- Request context (from middleware)
    parseArgs, // <- Input validator (from 'inputSchema')
    withDefaults, // <- Response helper (from 'outputSchema')
}) => {
 
    // Validate input and apply defaults, infers input types as well
    const { slug, ...postUpdates } = parseArgs(args)
 
    // -- Context / Auth Guards / Security --
 
    // e.g. use the request 'context' to log out current user
    const { user } = context // example, requires auth middleware
 
    // -- Business Logic --
 
    // e.g. update the post in the database
    const updatedPost = await Posts.updateOne({ slug }, postUpdates)
 
    // -- Respond --
 
    // Typecheck response and apply defaults from bridge's outputSchema
    return withDefaults({
        slug,
        title,
        content,
    })
 
}, updatePostBridge)

You pass the bridge (☝️) as the second argument to createResolver() to:

• 1️⃣ infer the input / arg types from the bridge’s inputSchema
• 2️⃣ enable parseArgs() and withDefaults() helpers for validation, hints + defaults
• 3️⃣ automatically extract the request context whether in an API route / GraphQL resolver / …

The resulting function can be used as just another async function anywhere in your back-end.

The difference with a regular function, since the logic is bundled together with its data-bridge / input + output metadata, is that we can easily transform it into APIs:

Turn resolver into an API route handler

We recommend workspaces follow Next.js API route conventions. This is so our scripts can automatically re-export them to the @app/next workspace later.

You can create a new API route by exporting a GET / POST / UPDATE / DELETE handler assigned to a createNextRouteHandler() that wraps your “bridged resolver”:

import { updatePost } from '@app/resolvers/updatePost.resolver'
import { createNextRouteHandler } from '@green-stack/schemas/createNextRouteHandler'
 
/* --- Routes ------------ */
 
export const UPDATE = createNextRouteHandler(updatePost)
// Automatically extracts (☝️) args from url / search params
// based on the zod 'inputSchema'
 
// If you want to support e.g. POST (👇), same deal (checks request body too)
export const POST = createNextRouteHandler(updatePost)

What createNextRouteHandler() does under the hood:

• 1. extract the input from the request context
• 2. validate it
• 3. call the resolver function with the args (and e.g. token / session / request context)
• 4. return the output from your resolver with defaults applied

Check Next.js Route Handlers to understand supported exports (like GET or POST) and their options.

Restart your dev server or run npm run collect:routes to make sure your new API route is available.

GraphQL, without the hassle

API routes are fine, but we think GraphQL is even better, if you don’t have to deal with the hassle of managing it. So we made it quite easy to enable GraphQL for your resolvers. The flow is quite similar.

In the same file, add the following:

import { updatePost } from '@app/resolvers/updatePost.resolver'
import { createNextRouteHandler } from '@green-stack/schemas/createNextRouteHandler'
import { createGraphResolver } from '@green-stack/sck,nhemas/createGraphResolver'
 
/* --- Routes ------------ */
 
// exports of `GET` / `POST` / `PUT` / ...
 
/* --- GraphQL ----------- */
 
export const graphResolver = createGraphResolver(updatePost)
// Automatically extracts input (☝️) from graphql request context

After exporting graphResolver here, restart the dev server or run npm run build:schema manually.

This will:

• 1. pick up the graphResolver export
• 2. put it in our list of graphql compatible resolvers at resolvers.generated.ts in @app/registries
• 3. recreate schema.graphql from input & output schemas from registered resolvers

You can now check out your GraphQL API playground at /api/graphql

Optional - Add a universal fetcher

We’ll mostly be using fetchers when providing data to our app screens or routes. You can skip this step as it will be covered on the next page as well.

import { updatePostBridge } from './updatePost.bridge'
// ☝️ Reuse your data bridge
import { bridgedFetcher } from '@green-stack/schemas/bridgedFetcher'
// ☝️ Universal graphql fetcher that can be used in any JS environment
 
/* --- updatePostFetcher() --------- */
 
export const updatePostFetcher = bridgedFetcher(updatePostBridge)

import { ResultOf, VariablesOf } from 'gql.tada'
// ☝️ Type helpers that interface with the GraphQL schema
import { graphql } from '../graphql/graphql'
// ☝️ Custom gql.tada query builder that integrates with our types
import { bridgedFetcher } from '@green-stack/schemas/bridgedFetcher'
// ☝️ Universal graphql fetcher that can be used in any JS environment
 
/* --- Query ----------------------- */
 
// VSCode and gql.tada will help suggest or autocomplete thanks to our schema definitions
export const updatePostQuery = graphql(`
  query updatePost ($updatePostArgs: UpdatePostInput) {
    updatePost(args: $updatePostArgs) {
      slug
      title
      body
    }
  }
`)
 
// ⬇⬇⬇ automatically typed as ⬇⬇⬇
 
// TadaDocumentNode<{
//     updatePost(args: Partial<Post>): {
//         slug: string | null;
//         title: boolean | null;
//         body: boolean | null;
//     };
// }>
 
// ⬇⬇⬇ can be turned into reusable types ⬇⬇⬇
 
/* --- Types ----------------------- */
 
export type UpdatePostQueryInput = VariablesOf<typeof updatePostQuery>
 
export type UpdatePostQueryOutput = ResultOf<typeof updatePostQuery>
 
/* --- updatePostFetcher() --------- */
 
export const updatePostFetcher = bridgedFetcher({
  ...updatePostBridge, // <- Reuse your data bridge ...
  graphqlQuery: updatePostQuery, // <- ... BUT, use our custom query
})