DEV Community: TheGuildBot

Understanding the Differences Between GraphQL and REST API Gateways

TheGuildBot — Tue, 03 Dec 2024 14:45:31 +0000

This article was published on Tuesday, December 3, 2024 by Saihajpreet Singh @ The Guild Blog

API gateways serve as crucial intermediaries between clients and backend services, but GraphQL and
REST gateways handle this responsibility quite differently. While a GraphQL gateway can be
considered a superset of REST gateway functionality, each has its distinct characteristics and use
cases.

Core Differences

Request Processing

REST API Gateway: Handles traditional HTTP requests with fixed endpoints. Each endpoint typically serves a specific purpose and returns a predefined data structure. The gateway routes these requests to appropriate microservices based on URL patterns.
GraphQL Gateway: Processes queries written in the GraphQL query language, typically through a single endpoint. It can understand complex queries requesting specific fields and relationships, making it more flexible in handling varied data requirements.

Data Aggregation

REST Gateway: Often requires multiple endpoints to gather related data, leading to potential over-fetching or under-fetching of data. The gateway might need to make several internal calls to different services to compose a complete response.
GraphQL Gateway: Excels at data aggregation by allowing clients to specify exactly what data they need in a single request. The gateway can efficiently collect data from multiple services based on the query structure.

Key Features and Capabilities

Caching

REST Gateway: Implements straightforward HTTP caching mechanisms. Responses can be cached based on URLs and HTTP methods.
GraphQL Gateway: Requires more sophisticated caching strategies due to the dynamic nature of queries. Often implements field-level caching and needs to consider query complexity.

Security

REST Gateway: Security is typically implemented at the endpoint level with traditional authentication and authorization mechanisms.
GraphQL Gateway: Provides more granular security controls, allowing permissions to be set at the field level. Can implement query complexity analysis to prevent abuse.

Schema Management

REST Gateway: No built-in schema management. API documentation typically relies on external tools like Swagger/OpenAPI.
GraphQL Gateway: Schema management can be as straightforward as maintaining schema definitions in code and versioning them with Git. Teams can choose between simple code-first approaches or leverage specialized tools like GraphQL Hive for more advanced schema registry and validation features. This flexibility allows teams to scale their schema management practices as their needs grow.

Service Integration

REST Gateway: No built-in way to integrate with other protocols.
GraphQL Gateway: A GraphQL gateway like Hive Gateway unifies multiple protocols (REST, gRPC, SOAP & many more) into a consistent interface using tools like GraphQL Mesh, while supporting federation capabilities that let teams independently develop and deploy subgraphs as part of a unified supergraph. Learn more about Federation here.

Why Choose GraphQL Gateway?

GraphQL gateways represent the future of API architecture for several compelling reasons:

Enhanced Developer Experience: GraphQL's intuitive query language and self-documenting nature significantly improve developer productivity.
Integration: Easily integrate legacy services and offer a unified query experience.
Optimal Performance: By allowing clients to request exactly what they need, GraphQL eliminates the over-fetching and under-fetching problems common with REST APIs.
Future-Proof Architecture: GraphQL's flexible schema system makes it easier to evolve your API over time without breaking existing clients.
Better Resource Utilization: The ability to combine multiple data requirements into a single request reduces server load and network overhead.
Strong Ecosystem: The GraphQL ecosystem offers excellent tools for monitoring, testing, and managing your API gateway.

Conclusion

While REST API gateways have served us well, GraphQL gateways offer superior capabilities for modern
applications. Their ability to handle complex data requirements efficiently, combined with excellent
developer experience and powerful tools, makes them the recommended choice for new API gateway
implementations. Organizations can start simple with basic schema management in Git and gradually
adopt more sophisticated tools like Hive as their needs evolve.

Extending your GraphQL service: Federation or Schema Stitching

TheGuildBot — Thu, 21 Nov 2024 14:16:40 +0000

This article was published on Monday, November 18, 2024 by Emily Goodwin @ The Guild Blog

If you're looking to extend your GraphQL service into separated services, you've likely come across
two key terms: schema stitching and federation. Even if these concepts are new to you, don't
worry—this post will introduce you to both approaches and help you understand their role in
enhancing your GraphQL infrastructure.

What Is GraphQL?

Let's start with a brief overview of GraphQL: it's a query language and runtime for APIs that work
with your existing data. GraphQL delivers precisely the data you need—no more, no less—and allows
APIs to evolve over time.

However as GraphQL gained widespread adoption, many companies faced growing pains with their
implementations. As their graphs grew, they began to face the challenges typical of monolithic
systems. These large graphs blurred the lines between distinct business domains, which is where
separating GraphQL services becomes beneficial.

There are several reasons why you might want to split your GraphQL service into smaller, separate
services:

Separate Business Domains

In most applications, data is already organized by business domains. For instance, the data and
logic behind a Users service are distinct from that of an Orders service. Separating your
GraphQL services allows you to maintain this natural separation, making it easier to manage,
develop, and scale each domain individually.

Scaling Requirements

As your GraphQL service grows, maintaining a single, monolithic system can lead to complexity and
performance issues. Different parts of the system may have varying scaling needs—for example,
user-related queries might need to handle more traffic than order-related ones. Splitting services
by domain allows each one to scale independently based on demand, improving both performance and
resource efficiency.

Simpler Ownership and Maintenance

Having distinct GraphQL schemas and resolvers for different services enables parallel development by
different teams. It also simplifies ownership and accountability, as each service can be managed and
maintained independently. Smaller, focused services are easier to understand, test, and deploy,
making long-term maintenance less burdensome compared to a single, complex monolith.

What Is the Solution?

The solution may seem straightforward: separate the different domains and information into different
schemas. But what happens when domains or information are related?

This is where schema stitching or federation comes into play. These approaches allow definitions to
relate data between different schemas.

Schema Stitching

Schema stitching takes many smaller services’ schemas and stitches them together to make a larger
schema. This larger schema is used by a proxy service, the gateway, to delegate different parts of
the query to different subschema services.

There are three main approaches to schema stitching:

Schema Extension (Gateway-Level Configuration)

Schema extension uses schema delegation to take different subschemas and extend them at the gateway
level.

Say you had a type, book and a type author in different schemas and services. At the gateway
level you can extend the type book with a new field author that delegates to the author
service.

Type Merging (Gateway-Level Configuration)

Type merging allows for partial definitions of a type to exist in any subschema which are all merged
into a unified type at the gateway.

This is useful if you have different standalone GraphQL APIs and you need to configure those at the
gateway level.

Lets consider a situation where you needed a type author but had two different services. In the
first service you would have the fields id and name . In the second service you would have the
fields id and description. In the gateway it would merge the author type to contain all the
fields id, description, and name. When you built a query it would go to the service that
declared the type.

Stitching Directives (Service Level Configuration)

Similar to Federation, schema stitching allows for directives-based approach of schema stitching.
This allows you to configure your merging at the service level versus the gateway level.

In this example you would use the @merge directive and @key directive with a selectionSet to
explain how to merge the schemas.

Federation

Federation lets you use directives to combine multiple APIs into a single federated graph.

When a user makes a request, it goes through the router. Based on the directives, the router
orchestrates and distributes the request across the APIs and returns a unified response.

This router needs a supergraph as a map to route to the different subgraphs, this supergraph can be
created by paid applications like GraphOS or free services such as The Guild’s own
Hive.

Federation introduces the concept of Entities which are federated types that exist across multiple
subgraphs.

Here is a comparison of Federation-Compatible Gateway Implementations:

https://the-guild.dev/graphql/hive/federation-gateway-audit

For more information on Federation and The Guild's support, please see here:

https://the-guild.dev/graphql/hive/federation

What Is the Overall Difference?

Schema stitching merges multiple schemas into a single unified schema by directly combining them. In
this setup, the gateway executes the requests by resolving data from multiple services, often
relying on custom logic to determine how to fetch and combine the data from different schemas.

Federation allows each subgraph to manage part of the unified schema independently. The central
gateway composes these subgraphs into a unified graph, and relationships between services are
handled through federation directives like @key, @provides, and @extends. The gateway uses
these directives to predetermine how data is fetched and merged across services.

This structure enables static checks, ensuring predictable behavior of the gateway in production. By
using tools like Hive CLI or Apollo Studio to create the supergraph, you can validate the schema
ahead of time, preventing conflicts before the supergraph is deployed. Additionally, these tools
provide insight into how the gateway will execute queries, giving you confidence in its behavior
after deployment.

The Guild’s products are compatible with both Federation and Schema Stitching.

Which One Is Better for Your Use Case?

This is a question only you can answer, but let’s look at common questions you should ask to
determine which approach is better for your use case.

	Schema Stitching	Federation
Customizability	More	Less
Scalability	Less	More
Collaboration	Less	More
GraphQL Knowledge Required for subschema/graphlet teams	Less	More
GraphQL Knowledge Required for Gateway team	More	Less

What is the overall GraphQL knowledge for the teams involved?

Federation requires more over knowledge of GraphQL from all teams involved as they need to work
together to make the federated schema work as expected. Schema Stitching requires less knowledge
from subschema teams but more knowledge from the team owning the gateway as the stitching logic can
become complex as the number of services grow.

What is your organizational structure?

If you have teams across organizations who need to collaborate, it may be better to use Apollo
Federation as it supports more collaboration on the schema so teams need to work together and
understand what each other is doing with their schema.

If you want to minimize the need for teams to collaborate closely, schema stitching might be a good
choice. With schema stitching, the gateway "magically" combines the services for the teams managing
subschemas. The gateway handles most of the stitching process, so subschema teams don't need to
worry about how their schemas are integrated.

How fast do you need to build your solution?

Schema Stitching is usually a faster approach for smaller or simpler projects since it is straight
forward. You can combine schemas quickly without much additional infrastructure but it takes longer
to develop as the overall service grows.

Federation takes a bit longer to set up as it requires multiple subgraphs, a gateway, and a
registry. As the services grow, Federation can speed up development for teams since each team
independently manages their service.

How customizable does your implementation of the gateway need to be?

Schema stitching allows for a deeper customization of schemas, resolvers, and transformations since
you have full control over how each service is combined.

Federation is more suited for scalability and team collaboration. Customization is more structured
through federation directives.

If you would like to talk to an expert in regards to your GraphQL implementation, feel free to get
in touch with The Guild here.

GraphQL Response Caching with Envelop

TheGuildBot — Fri, 15 Nov 2024 11:53:58 +0000

This article was published on Thursday, August 19, 2021 by Laurin Quast @ The Guild Blog

A Brief Introduction to Caching

Huge GraphQL query operations can slow down your server as deeply nested selection sets can cause a
lot of subsequent database reads or calls to other remote services. Tools like DataLoader can
reduce the amount of concurrent and subsequent requests via batching and caching during the
execution of a single GraphQL operation. Features like @defer and @stream can help with
streaming slow-to-retrieve result partials to the clients progressively. However, for subsequent
requests we hit the same bottle-neck over and over again.

What if we don't need to go through the execution phase at all for subsequent requests that execute
the same query operation with the same variables?

A common practice for reducing slow requests is to leverage caching. There are many types of caching
available. E.g. We could cache the whole HTTP responses based on the POST body of the request or an
in memory cache within our GraphQL field resolver business logic in order to hit slow services less
frequently.

Having a cache comes with the drawback of requiring some kind of cache invalidation mechanism.
Expiring the cache via a TTL (time to live) is a widespread practice, but can result in hitting the
cache too often or too scarcely. Another popular strategy is to incorporate cache invalidation logic
into the business logic. Writing such logic can potentially become too verbose and hard to maintain.
Other systems might use database write log observers for invalidating entities based on updated
database rows.

In a strict REST API environment, caching entities is significantly easier, as each endpoint
represents one resource, and thus a GET method can be cached and a PATCH method can be used for
automatically invalidating the cache for the corresponding GET request, which is described via the
HTTP path (/api/user/12).

With GraphQL such things become much harder and complicated. First, we usually only have a single
HTTP endpoint /graphql that only accepts POST requests. A query operation execution result could
contain many different types of entities, thus, we need different strategies for caching GraphQL
APIs.

SaaS services like FastQL and GraphCDN started popping providing proxies for your existing GraphQL
API, that magically add response based caching. But how does this even work?

How Does GraphQL Response Caching Work?

Caching Query Operations

In order to cache a GraphQL execution result (response) we need to build an identifier based on the
input that can be used to identify whether a response can be served from the cache or must be
executed and then stored within the cache.

Example: GraphQL Query Operation

query UserProfileQuery($id: ID!) {
  user(id: $id) {
    __typename
    id
    login
    repositories
    friends(first: 2) {
      __typename
      id
      login
    }
  }
}

Example: GraphQL Variables

{
  "id": "1"
}

Usually those inputs are the Query operation document and the variables for such an operation
document.

Thus, a response cache can store the execution result under a cache key that is built from those
inputs:

OperationCacheKey (e.g. SHA1) = hash(GraphQLOperationString, Stringify(GraphQLVariables))

Under some circumstances it is also required to cache based on the request initiator. E.g. a user
requesting his profile should not receive the cached profile of another user. In such a scenario,
building the operation cache key should also include a partial that uniquely identifies the
requestor. This could be a user ID extracted from an authorization token.

OperationCacheKey (e.g. SHA1) = hash(GraphQLOperationString, Stringify(GraphQLVariables), RequestorId)

This allows us to identify recurring operations with the same variables and serve it from the cache
for subsequent requests. If we can serve a response from the cache we don't need to parse the
GraphQL operation document and furthermore can skip the expensive execution phase. That will result
in significant speed improvements.

But in order to make our cache smart we still need a suitable cache invalidation mechanism.

Invalidating Cached GraphQL Query Operations

Let's take a look at a possible execution result for the GraphQL operation.

Example: GraphQL Execution Result

{
  "data": {
    "user": {
      "__typename": "User",
      "id": "1",
      "login": "dotan",
      "repositories": ["codegen"],
      "friends": [
        {
          "__typename": "User",
          "id": "2",
          "login": "urigo"
        },
        {
          "__typename": "User",
          "id": "3",
          "login": "n1ru4l"
        }
      ]
    }
  }
}

Many frontend frameworks cache GraphQL operation results in a normalized cache. The identifier for
storing the single entities of a GraphQL operation result within the cache is usually the id field
of object types for schemas that use global unique IDs or a compound of the __typename and id
field for schemas that use non-global ID fields.

Example: Normalized GraphQL Client Cache

{
  "User:1": {
    "__typename": "User",
    "id": "1",
    "login": "dotan",
    "repositories": ["codegen"],
    "friends": ["$$ref:User:2", "$$ref:User:3"]
  },
  "User:2": {
    "__typename": "User",
    "id": "2",
    "login": "urigo"
  },
  "User:3": {
    "__typename": "User",
    "id": "3",
    "login": "n1ru4l"
  }
}

Interestingly, the same strategy for constructing cache keys on the client can also be used on the
backend for tracking which GraphQL operations contain which entities. That allows invalidating
GraphQL query operation results based on entity IDs.

For the execution result entity IDS that could be used for invalidating the operation are the
following: User:1, User:2 and User:3.

And also keep a register that maps entities to operation cache keys.

Entity   List of Operation cache keys that reference a entity

User:1   OperationCacheKey1, OperationCacheKey2, ...
User:2   OperationCacheKey2, OperationCacheKey3, ...
User:3   OperationCacheKey3, OperationCacheKey1, ...

This allows us to keep track of which GraphQL operations must be invalidated once a certain entity
becomes stale.

The remaining question is, how can we track an entity becoming stale?

As mentioned before, listening to a database write log is a possible option - but the implementation
is very specific and differs based on the chosen database type. Time to live is also a possible, but
a very inaccurate solution.

Another solution is to add invalidation logic within our GraphQL mutation resolver. By the GraphQL
Specification mutations are meant to modify our GraphQL graph.

A common pattern when sending mutations from clients is to select and return affected/mutated
entities with the selection set.

For our example from above the following could be a possible mutation for adding a new repository to
the repositories field on the user entity.

Example: GraphQL Mutation

mutation RepositoryAddMutation($userId: ID, $repositoryName: String!) {
  repositoryAdd(userId: $userId, repositoryName: $repositoryName) {
    user {
      id
      repositories
    }
  }
}

Example: GraphQL Mutation Execution Result

{
  "data": {
    "repositoryAdd": {
      "user": {
        "id": "1",
        "repositories": ["codegen", "envelop"]
      }
    }
  }
}

Similar to how we build entity identifiers from the execution result of query operations for
identifying what entities are referenced in which operations, we can extract the entity identifiers
from the mutation operation result for invalidating affected operations.

In this specific case all operations that select User:1 should be invalidated.

Such an implementation makes the assumption that all mutations by default select affected entities
and, furthermore, all mutations of underlying entities are done through the GraphQL gateway via
mutations. In a scenario where we have actors that are not GraphQL services or services that operate
directly on the database, we can use this approach in a hybrid model with other methods such as
listening to database write logs.

Envelop Response Cache

The Envelop response cache plugin now provides primitives and a reference in memory store
implementation for adopting such a cache with all the features mentioned above with any GraphQL
server.

The goal of the response cache plugin is to educate how such mechanisms are implemented and
furthermore give developers the building blocks for constructing their own global cache with their
cloud provider of choice.

Adding a response cache to an existing envelop GraphQL server setup is as easy as adding the plugin:

import { envelop } from '@envelop/core'
import { useResponseCache } from '@envelop/response-cache'

const getEnveloped = envelop({
  plugins: [
    // ... other plugins ...
    useResponseCache()
  ]
})

If you need to imperatively invalidate you can do that by providing the cache to the plugin:

import { envelop } from '@envelop/core'
import { createInMemoryCache, useResponseCache } from '@envelop/response-cache'
import { emitter } from './event-emitter'

const cache = createInMemoryCache()

emitter.on('invalidate', entity => {
  cache.invalidate([
    {
      typename: entity.type,
      id: entity.id
    }
  ])
})

const getEnveloped = envelop({
  plugins: [
    // ... other plugins ...
    useResponseCache({ cache })
  ]
})

The caching behavior can be fully customized. A TTL can be provided global or more granular per type
or schema coordinate.

import { envelop } from '@envelop/core'
import { useResponseCache } from '@envelop/response-cache'

const getEnveloped = envelop({
  plugins: [
    // ... other plugins ...
    useResponseCache({
      // cache operations for 1 hour by default
      ttl: 60 * 1000 * 60,
      ttlPerType: {
        // cache operation containing Stock object type for 500ms
        Stock: 500
      },
      ttlPerSchemaCoordinate: {
        // cache operation containing Query.rocketCoordinates selection for 100ms
        'Query.rocketCoordinates': 100
      },
      // never cache responses that include a RefreshToken object type.
      ignoredTypes: ['RefreshToken']
    })
  ]
})

Need to cache based on the user? No problem.

import { envelop } from '@envelop/core'
import { useResponseCache } from '@envelop/response-cache'

const getEnveloped = envelop({
  plugins: [
    // ... other plugins ...
    useResponseCache({
      // context is the GraphQL context that would be used for execution
      session: context => (context.user ? String(context.user.id) : null),
      // never serve cache for admin users
      enabled: context => (context.user ? isAdmin(context.user) === false : true)
    })
  ]
})

Don't want to automatically invalidate based on mutations? Also, configurable!

import { envelop } from '@envelop/core'
import { useResponseCache } from '@envelop/response-cache'

const getEnveloped = envelop({
  plugins: [
    // ... other plugins ...
    useResponseCache({
      // some might prefer invalidating only based on a database write log
      invalidateViaMutation: false
    })
  ]
})

Want a global cache on Redis? Build a cache that implements the Cache interface and share it with
the community!

export type Cache = {
  /** set a cache response */
  set(
    /** id/hash of the operation */
    id: string,
    /** the result that should be cached */
    data: ExecutionResult,
    /** array of entity records that were collected during execution */
    entities: Iterable<CacheEntityRecord>,
    /** how long the operation should be cached */
    ttl: number
  ): PromiseOrValue<void>
  /** get a cached response */
  get(id: string): PromiseOrValue<Maybe<ExecutionResult>>
  /** invalidate operations via typename or id */
  invalidate(entities: Iterable<CacheEntityRecord>): PromiseOrValue<void>
}

More information about all possible configuration options can be found on
the response cache docs on the Plugin Hub.

What Is Next?

We are excited to explore new directions and make enterprise solutions accessible for all kinds of
developers.

What if the response cache could be used as a proxy on edge cloud functions distributed around the
world, which would allow using envelop as a http proxy to your existing GraphQL server? This is
something we would love to explore more (or even see contributions and projects from other
open-source developers).

We also want to make other practices such as rate limits based on operation cost calculation as used
by huge corporations like Shopify available as envelop plugins.

Do you have any ideas, want to contribute or report issues? Start a GitHub discussion/issue or
contact us via the chat!

How to write GraphQL resolvers effectively

TheGuildBot — Mon, 04 Nov 2024 13:05:23 +0000

This article was published on Monday, November 4, 2024 by Eddy Nguyen @ The Guild Blog

Resolvers are the fundamental building blocks of a GraphQL server. To build a robust and scalable
GraphQL server, we must understand how to write GraphQL resolvers effectively. In this blog post, we
will explore:

how resolvers work
concepts such as resolver map, resolver chain, defer resolve and mappers
tools and best practices

Glossary

Resolver map: An object containing resolvers that match the types and fields in the GraphQL schema.
Resolver chain: The order of resolvers execution when the GraphQL server handles a request.
Mapper: The shape of the data returned by a resolver to become the parent parameter of the next resolver in the resolver chain.
Defer resolve: A technique to avoid unnecessary resolver execution of a field early in the resolver chain.

What Are Resolvers?

In a GraphQL server, a resolver is a function that "resolves" a value which means doing arbitrary
combination of logic to return a value. For example:

returning a value statically
fetching data from a database or an external API to return a value
executing a complex business logic to return a value

Each field in a GraphQL schema has an optional corresponding resolver function. When a client
queries a field, the server executes the resolver function to resolve the field.

Given this example schema:

```graphql filename="src/graphql/schema.graphql"
type Query {
movie(id: ID!): Movie
}

type Movie {
id: ID!
name: String!
actors: [Actor!]!
}

type Actor {
id: ID!
stageName: String!
}




We can write a **resolver map** like this:



```ts filename="src/graphql/resolvers.ts"
const resolvers = {
  Query: {
    movie: () => {} // `Query.movie` resolver
  },
  Movie: {
    id: () => {}, // `Movie.id` resolver
    name: () => {}, // `Movie.name` resolver
    actors: () => {} // `Movie.actors` resolver
  },
  Actor: {
    id: () => {}, // `Actor.id` resolver
    stageName: () => {} // `Actor.stageName` resolver
  }
}

We will discuss how the code flows through resolvers when the server handles a request in the next
section.

Code Flow and Resolver Chain

Using the same schema, we may send a query like this:

query Movie {
  movie(id: "1") {
    id
    name
    actors {
      id
      stageName
    }
  }
}

Once the server receives this query, it starts at Query.movie resolver, and since it returns a
nullable Movie object type, two scenarios can happen:

If Query.movie resolver returns null or undefined, the code flow stops here, and the server returns movie: null to the client.
If Query.movie resolver returns anything else (e.g. objects, class instances, number, non-null falsy values, etc.), the code flow continues. Whatever being returned - usually called mapper - will be the first argument of the Movie resolvers i.e. Movie.id and Movie.name resolvers.

This process repeats itself until a GraphQL scalar field needs to be resolved. The order of the
resolvers execution is called the resolver chain. For the example request, the resolver chain
may look like this:

flowchart LR
  A[Query.movie] --> B(Movie.id)
  A[Query.movie] --> C(Movie.name)
  A[Query.movie] --> D(Movie.actors)
  D --> E(Actor.id)
  D --> F(Actor.stageName)

There are four positonal arguments of a resolver function:

parent: the value returned by the parent resolver.
- For root-level resolvers like Query.movie, parent is always undefined.
- For other object-type resolvers like Movie.id and Movie.name, parent is the value returned by parent resolvers like Query.movie
args: this is the arguments passed by client operations. In our example query, Query.movie resolver would receive { id: "1" } as args
context: An object passed through the resolver chain. It is useful for passing information between resolvers, such as authentication information, database connection, etc.
info: An object containing information about the operation, such as operation AST, path to the resolver, etc.

We must return a value that can be handled by the scalars. In our example:

Movie.id and Actor.id resolvers must return a non-nullable value that can be coerced into the ID scalar i.e. string or number values.
Movie.name and Actor.stageName resolver must return a non-nullable value that can be coerced into the String scalar i.e. string, boolean or number values.

You can learn about GraphQL Scalar, including native Scalar and coercion concept, in this guide
here

It is important to remember that we will encounter runtime errors if the resolver returns unexpected
values. Some common scenarios are:

a resolver returns null to a non-nullable field
a resolver returns a value that cannot be coerced into the expected scalar type
a resolver returns a non-array value to an array field, such as Movie.actors

How to Implement Resolvers

Implementing Resolvers - Or Not

If an empty resolver map is provided to the GraphQL server, the server still tries to handle
incoming requests. However, it will return null for every root-level field in the schema. This
means if a root-level field like Query.movie's return type is non-nullable, we will encounter
runtime error.

If object type resolvers are omitted, the server will try to return the property of the same name
from parent. Here's what Movie resolvers may look like if they are omitted:

const resolvers = {
  Movie: {}, // 👈 Empty `Movie` resolvers object,
  Movie: undefined, // 👈 or undefined/omitted `Movie` resolvers object...

  // 👇 ...are the equivalent of the following `Movie` resolvers:
  Movie: {
    id: parent => parent.id,
    name: parent => parent.name,
    actors: parent => parent.actors
  }
}

This means if Query.movie resolver returns an object with id, name, and actors properties,
we can omit the Movie and Actor resolvers:

const resolvers = {
  Query: {
    movie: () => {
      return {
        id: '1',
        name: 'Harry Potter and the Half-Blood Prince',
        actors: [
          { id: '1', stageName: 'Daniel Radcliffe' },
          { id: '2', stageName: 'Emma Watson' },
          { id: '3', stageName: 'Rupert Grint' }
        ]
      }
    }
  }
  // 💡 `Movie` and `Actor` resolvers are omitted here but it still works,
  // Thanks to default resolvers!
}

In this very simple example where we are returning static values, this will work. However, in a
real-world scenario where we may fetch data from a database or an external API, we must consider the
response data shape, and the app performance. We will try to simlulate a real-world scenario in the
next section.

Implementing Resolvers for Real-World Scenarios

Below is an object this can be used as an in-memory database:

const database = {
  movies: {
    // Movies table
    '1': {
      id: '1',
      movieName: 'Harry Potter and the Half-Blood Prince'
    }
  },
  actors: {
    // Actors table
    '1': {
      id: '1',
      stageName: 'Daniel Radcliffe'
    },
    '2': {
      id: '2',
      stageName: 'Emma Watson'
    },
    '3': {
      id: '3',
      stageName: 'Rupert Grint'
    }
  },
  movies_actors: {
    // Table containing movie-actor relationship
    '1': {
      // Movie ID
      actorIds: ['1', '2', '3']
    }
  }
}

We usually pass database connection through context, so we might update Query.movie to look like
this:

const resolvers = {
  Query: {
    movie: (_, { id }, { database }) => {
      const movie = database.movies[id] // 🔄 Database access counter: (1)

      if (!movie) {
        return null
      }

      return {
        id: movie.id,
        name: movie.movieName,
        actors: (database.movies_actors[id] || []).actorIds // 🔄 (2)
          .map(actorId => {
            return database.actors[actorId] // 🔄 (3), 🔄 (4), 🔄 (5)
          })
      }
    }
  }
}

This works, however, there are a few issues:

We are accessing the database 5 times every time Query.movie runs (Counted using 🔄 emoji in the previous code snippet). Even if the client may not request for actors field, this still happens. So, we are making unnecessary database calls. This is called eager resolve.
We are mapping movie.movieName in the return statement. This is fine here, but our schema may scale to have multiple fields returning Movie, and we may have to repeat the same mapping logic in multiple resolvers.

To improve this implementation, we can use mappers and defer resolve to avoid unnecessary
database calls and reduce code duplication:

type MovieMapper = {
  // 1.
  id: string
  movieName: string
}
type ActorMapper = string // 2.

const resolvers = {
  Query: {
    movie: (_, { id }, { database }): MovieMapper => {
      const movie = database.movies[id]

      if (!movie) {
        return null
      }

      return movie // 3.
    }
  },
  Movie: {
    name: (parent: MovieMapper) => parent.movieName, // 4.
    actors: (parent: MovieMapper, _, { database }): ActorMapper[] =>
      database.movies_actors[parent.id].actorIds // 5.
    // 6.
  },
  Actor: {
    id: (parent: ActorMapper) => parent, // 7.
    stageName: (parent: ActorMapper, _, { database }) => database.actors[parent].stageName // 8.
  }
}

We define a MovieMapper type to represent the shape of the object returned by Query.movie resolver.
Similarly, we define ActorMapper to be returned wherever Actor type is expected. Note that in this example, ActorMapper is a string representing the ID of an actor in this case, instead of an object.
The MovieMapper is returned by Query.movie resolver, and it becomes the parent of Movie resolvers in (4) and (5).
Since MovieMapper has movieName property, but the GraphQL type expects String scalar for name instead. So, we need to return the mapper's movieName to the schema's Movie.name field.
MovieMapper doesn't have actors property, so we must find all the related actors from the database. Here, we expect an array of ActorMapper (i.e. an array of string) to be returned, which is the actorIds array in the database. This just means the parent of each Actor resolver is a string in (7) and (8)
We can skip implementing Movie.id resolver because by default it passes MovieMapper.id property safely.
Because each ActorMapper is the ID of an actor, we return the parent instead of parent.id
Similarly, we use parent as the ID of the actor to fetch the actor's stageName from the database.

By using mappers and defer resolve techniques, we avoid unnecessary database calls and
reduce code duplication. The next time we need to write a resolver that returns Movie, Actor
objects, we can simply return the corresponding mapper objects.

Implementing Resolvers with Mappers and Defer Resolve Best Practices

We saw the benefits of using mappers and defer resolve in the previous section. Here are some
TypeScript best practices to keep in mind when implementing these techniques, failing to enforce
them may result in runtime errors:

Mappers MUST be correctly typed as the return type of a resolver and the parent type of the next resolver.
Object resolvers MUST be implemented if the expected schema field does not exist in the mapper or, the mapper's field cannot be coerced into the expected schema type of the same name.

At a small scale, it is easy to keep track of the types and mappers. However, as our schema grows,
it becomes harder to maintain the typing and remembering which resolvers to implement. This is where
tools like GraphQL Code Generator and
Server Preset can be used:

GraphQL Code Generator: generates TypeScript types for the resolvers, focusing on correct nullability, array and types.
Server Preset: generates and wires up resolvers conveniently, and runs analysis to suggests resolvers that require implementation, reducing the risk of runtime errors.

To get started, install the required packages:

```sh npm2yarn
npm i -D @graphql-codegen/cli @eddeee888/gcg-typescript-resolver-files




Next, create a `codegen.ts` file at the root of your project:



```ts filename="codegen.ts"
import { defineConfig } from '@eddeee888/gcg-typescript-resolver-files'
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'src/graphql/schema.graphql',
  generates: {
    'src/graphql': defineConfig({
      resolverGeneration: 'minimal'
    })
  }
}
export default config

Then, add mappers into schema.mappers.ts file, in the same directory as schema.graphql:

```ts filename="src/graphql/schema.mappers.ts"
type MovieMapper = {
id: string
movieName: string
}
type ActorMapper = string




<Callout type="info" emoji="💡">
  Server Preset automatically detects and wires up mappers if they follow the convention:

  1.  The mappers are declared in a file in the same directory as the schema source file, and has the file name ending with `.mappers.ts` segment instead of the schema source file's extension. For example:
      *   If your schema file is `schema.graphql`, the mappers file is `schema.mappers.ts`.
      *   If your schema file is `schema.graphql.ts`, the mappers file is `schema.graphql.mappers.ts`.
  2.  The mapper type names are in the format of `<TypeName>Mapper` where `<TypeName>` is the GraphQL schema name. For example:
      *   If the schema type is `Movie`, then the mapper type is `MovieMapper`.
</Callout>

Finally, run codegen to generate resolvers:



```sh npm2yarn
npm run graphql-codegen

We will see generated resolver files in src/graphql directory:

```ts filename="src/graphql/resolvers/Query/movie.ts"
import type { QueryResolvers } from './../../types.generated'

export const movie: NonNullable = async (_parent, _arg, _ctx) => {
/* Implement Query.movie resolver logic here */
}






```ts filename="src/graphql/resolvers/Movie.ts"
import type { MovieResolvers } from './../types.generated'

export const Movie: MovieResolvers = {
  /* Implement Movie resolver logic here */
  actors: async (_parent, _arg, _ctx) => {
    /* Movie.actors resolver is required because Movie.actors exists but MovieMapper.actors does not */
  },
  name: async (_parent, _arg, _ctx) => {
    /* Movie.name resolver is required because Movie.name exists but MovieMapper.name does not */
  }
}

```ts filename="src/graphql/resolvers/Actor.ts"
import type { ActorResolvers } from './../types.generated'

export const Actor: ActorResolvers = {
/* Implement Actor resolver logic here /
id: async (_parent, _arg, _ctx) => {
/ Actor.id resolver is required because Actor.id exists but ActorMapper.id does not /
},
stageName: async (_parent, _arg, _ctx) => {
/ Actor.stageName resolver is required because Actor.stageName exists but ActorMapper.stageName does not */
}
}




By providing mappers, codegen is smart enough to understand that we want to defer resolve, and we
need to write logic for `Movie.actors`, `Movie.name`, `Actor.id` and `Actor.stageName` resolvers to
ensure we don't encounter runtime errors.

<Callout type="info" emoji="💡">
  Learn how to set up GraphQL Code Generator and Server Preset for GraphQL Yoga and Apollo Server in
  this guide
  [here](https://the-guild.dev/graphql/codegen/docs/guides/graphql-server-apollo-yoga-with-server-preset).
</Callout>

## Summary

In this article, we have explored how resolvers work in a GraphQL server resolver code flow and
**resolver chain**, and how to write resolvers effectively using **mappers** and **defer resolve**
techniques. Finally, we add GraphQL Code Generator and Server Preset to automatically generate
resolvers and their types to ensure strong type-safety and reduce runtime errors.

The Guild acquires Stellate

TheGuildBot — Tue, 10 Sep 2024 14:56:06 +0000

This article was published on Tuesday, September 10, 2024 by Uri Goldshtein @ The Guild Blog

Today we are very pleased to announce that we have acquired
Stellate
GraphQL CDN - the leading GraphQL Caching solution.

The Stellate team has created an innovative platform, industry leading solution for GraphQL Caching,
fulfilling GraphQL's full potential for caching, enabling its superiority over all REST based
caching solutions.

The Guild's goal - providing an open platform with everything a
developer needs to take GraphQL into production, fits perfectly with Stellate's superb execution.

That's why acquiring Stellate and integrating it into our
GraphQL Hive Open Platform makes so much sense.

We've always prided ourselves on being the provider the GraphQL community can count on for the long
term.\
In the past, we've taken maintainership of a number of popular solutions, to give them new life and
improve them to the be industry leading solutions:

We've taken ownership of the famous GraphQL Tools library from Apollo - improving it for many years and recently integrating it into our Hive Gateway - our open source gateway that fully supports Apollo Federation.
We've taken ownership of GraphQL Yoga from Prisma - making it the leading Subgraph and GraphQL server for the JS ecosystem.
We've done the same with many other libraries and continuously support official GraphQL Foundation projects like GraphiQL, GraphQL-HTTP, GraphQL's official website and many more.

We offer GraphQL Hive to our users - a fully featured, complete 360˚ GraphQL platform that includes
a schema registry, analytics platform, Federated Gateway - available either as a hosted platform or
as a fully open-source, self-hosted solution under the
MIT license.

And now with an industry leading global GraphQL Edge Caching CDN!

Like all of our other projects, this is just the start! We are looking to hear from you, where you
wish us to take Stellate and our platform in the future.

Existing Stellate users, we are here for you. Reach out directly and schedule a call with us, we
want to learn about your current GraphQL experience and how the existing solutions can work better
for you.

To everyone else, try Stellate today,
try Hive today and let us know
what you wish the future of GraphQL to look like.

See you all at GraphQL Conf!

Introducing GraphQL Mesh v1 and Hive Gateway v1

TheGuildBot — Tue, 10 Sep 2024 14:26:47 +0000

This article was published on Tuesday, September 10, 2024 by Arda Tanrikulu @ The Guild Blog

We, The Guild, are proud to announce both the Version 1 release of
GraphQL Mesh and
Hive Gateway, and we believe this release brings
a new perspective to GraphQL Federation that we
call “Query Anything, Run Anywhere”.

After several years of experience with composed APIs with early v0 versions of GraphQL Mesh and
Schema Stitching, we have completely rebuild GraphQL Mesh from scratch for GraphQL Federation.

TL;DR: The previous GraphQL Mesh is now split into two complimentary projects:

GraphQL Mesh: Compose and Transform Datasources into a Federated GraphQL Schema. Query anything anywhere. Get started with GraphQL Mesh

Hive Gateway: Our Federation Gateway for that integrates with GraphQL Mesh and Schema registries such as GraphQL Hive or Apollo Studio. Get started with Hive Gateway

What is Hive Gateway? {/* eslint-disable-line mdx/remark */}

Hive Gateway is our fully
open source and
MIT-licensed GraphQL Gateway with
native support for GraphQL Federation.

It is designed to fully integrate with with our GraphQL Hive Platform offering, but also neatly
integrates with other Schema Registries such as Apollo Studio.

Hive Gateway is built on top of our existing and widely used open-source packages such as
GraphQL Yoga and
GraphQL Tools.

With Hive Gateway adding these features is now a simple configuration change, no enterprise
license is required!

GraphQL Subscriptions (via WebSocket, SSE, or HTTP Callbacks)
GraphQL API Usage and Analytics Reporting (GraphQL Hive or Apollo Studio)
Authentication and Authorization (JWT)
Role-based Access Control (RBAC)
Observability with Open Telemetry and Prometheus
Caching
Rate Limiting
Persisted Documents
Query Complexity Analysis
And more…

We listened to the feedback of the companies using Version 0 of GraphQL Mesh, and decided that Hive
Gateway should be as easy-to-use and be batteries-included by default. Many of our users are not as
versed and deep within the JavaScript and npm eco-system. The new configuration is designed in a way
to be approachable for users from all backgrounds.

Getting started is easy, whether you're already using the Hive Schema Registry, Apollo GraphOS, or
local subgraphs. With just a few lines of configuration, you'll end up with a running Gateway in no
time.

How well does Hive Gateway support GraphQL Federation? {/* eslint-disable-line mdx/remark */}

We put in a lot of effort over the last year into having a Federation compatibility test suite. We
rebuilt our Federation Query Planner and Execution Engine completely from scratch from these
learnings and now open-sources the test suite so other Apollo Federation Gateways can too benefit
from our research as well. It already helped to discover and report some regressions in Apollo
Router to the Apollo Team. We hope that this test suite will overall enhance the quality of all the
GraphQL gateways on the market.

Do I have to use the Hive Registry? {/* eslint-disable-line mdx/remark */}

No. You can gradually migrate to the Hive platform if desired. If you want to use your existing
schema registry (e.g. GraphOS), Hive Gateway supports these registries as well. You don't have to
migrate to the Hive Platform if you are just looking for a replacement to Apollo Router or Apollo
Gateway.

Deploy and Run Anywhere {/* eslint-disable-line mdx/remark */}

Hive Gateway can run anywhere. No need to mess with JavaScript and Node.js. You can choose your
preferred way:

Single Executable Binary
Docker Image
NPM package
If you are a JavaScript Tinkerer
- Node.js, Bun, or Deno
- Cloudflare Workers, AWS Lambda, Azure Functions and Google Cloud Functions.
- Integrate with your existing server framework such as Express, Fastify, Hapi and Koa.

What about GraphQL Mesh? {/* eslint-disable-line mdx/remark */}

Previously what is now known as Hive Gateway has been one of the many building block of GraphQL
Mesh. The other significant building block of GraphQL Mesh is the possibility to convert and compose
any amount of APIs such as REST/OpenAPI, SOAP, gRPC or even a database like MySQL into a single
unified GraphQL API, while applying a wide range of transforms e.g. for renaming or filtering the
output API types.

A lot of our clients have been using this approach to transform legacy APIs and all kind of other
sources for many years with great success.

From now on, GraphQL Mesh now only focuses only on composing datasources into a single annotated
GraphQL/Supergraph SDL file that is 100% compatible with Apollo Federation.

Serving the composed GraphQL schema is now a concern of Hive Gateway, which seamlessly integrates
with GraphQL Mesh.

All of the features introduced in GraphQL Mesh v0 remain unchanged. However, GraphQL Mesh now builds
on top of the Apollo Federation specification. That means you do all the conversion, generation and
stitching process at build time once, and then you generate a supergraph or subgraph SDL that can be
consumed by any
Apollo Federation compatible gateway.

To summarize, GraphQL Mesh is a framework that allows you to convert any API (REST, SOAP etc) into
the Apollo Federation subgraph to be consumed by a gateway. For the best experience, we recommend
using GraphQL Hive Gateway.

💡 GraphQL Mesh extends Apollo Federation to consume OpenAPI, SOAP and other non GraphQL sources, and also transform them by renaming fields and so on.
Of course within the boundaries of Apollo Federation specification!

How can I migrate to v1? {/* eslint-disable-line mdx/remark */}

While GraphQL Mesh v1 introduces several breaking changes, the core functionality remain the same as
in v0. All transforms, plugins, and other features are still available through the combination of
GraphQL Mesh and Hive Gateway. Simply follow our migration guides to make the transition. And as
always, feel free to reach out to us directly for assistance.

However, there's no need to rush your migration — we will continue to maintain v0 for the
foreseeable future.

What is the relationship between GraphQL Mesh and Hive Gateway? {/* eslint-disable-line mdx/remark */}

GraphQL Mesh generates a GraphQL Federation subgraph from a non GraphQL source (OpenAPI, SOAP, gRPC
etc) and/or a GraphQL API that doesn't have federation metadata. Then you can either compose that
subgraph with Mesh, or publish it to the schema registry, or compose it using other tools like
Apollo Rover to get a Federation Supergraph. Then this generated supergraph is consumed by a GraphQL
Gateway like Hive Gateway.

Query Anything, Run Anywhere

As our initial motto from the earlier stages of GraphQL Mesh. We still follow it.

This time we combined this idea with Apollo Federation. GraphQL Mesh now federates non GraphQL and
GraphQL sources on top of the official Apollo Federation specification.

Hive Gateway is there to orchestrate calls to those APIs and serve the responses to the client. You
can use them together or take one of them and use with other alternatives.

Both are free, open-source, MIT-licensed, without the need to pay extra for enterprise grade
features.

Audit of GraphQL Gateways Supporting Apollo Federation

TheGuildBot — Tue, 10 Sep 2024 14:26:16 +0000

This article was published on Tuesday, September 10, 2024 by Kamil Kisiela @ The Guild Blog

The Apollo Federation spec is a hot topic, we must admit. The adoption of it keeps increasing,
especially over past two years. There's a reason! It's a fantastic piece of technology, but also a
complex piece of tech.

If you're curious about the results,
visit the audit page

Complexity Is Not Obvious{/* eslint-disable-line mdx/remark */}

As a user of Apollo Federation, you might not see the full spectrum of
Apollo Federation.

When building subgraphs, you might occasionally encounter composition errors, but ultimately,
everything works and you query data. The real complexity lies in tooling, starting with the
composition library, and ending on the gateway and it's query planning.

As maintainers of Hive Gateway
(previously part of GraphQL Mesh) and creators of GraphQL
Hive (our Schema Registry for GraphQL Federation), we've seen a wide range of supergraphs. Over the
past few years, we've been working with companies adopting or already using Apollo Federation in
production.

We learned something, actually quite a lot!

Today, we're even collaborating with creators of Apollo Federation and the
ChilliCream teams (who built
GraphQL Fusion) on
the new specification for federated GraphQL APIs,
as proud members of GraphQL Foundation.

We've seen Apollo Federation's complexity, we understood the rules of it very well, and we have
something incredibly interesting to share!

Before we get to that, let's first discuss what does it mean to "support Apollo Federation" on a
gateway.

What Does "Apollo Federation Support" Really Mean?{/* eslint-disable-line mdx/remark */}

As you know, the spec contains a lot of directives, and these can be used in various ways, resulting
in many combinations. Sometimes weird at first glance, but when you really think about them,
they make sense.

In a lot of cases, the spec is abused, but hey… what's allowed, has to work!

Most of the time you will see “Apollo Federation support” phrase or a list of supported directives,
and this is fine, but it tells only a part of the story.

If a gateway supports the @key directive, it may or may not support it on an Interface type, for
example. You simply don't know until you try it!

Did you know that in Apollo Federation v1, a field that is annotated with @external, that is also
part of key fields, and is not defined anywhere else, is still resolvable?

extend type Product @key(fields: "id name") @key(fields: "upc") {
  id: ID @external
  name: String @external
  upc: String @external
  price: Float!
}

Not everyone knows that key fields of extension types in Federation v1, must be annotated with
@external , and these are still resolvable by the subgraph. That's why we built the audit!

Here's how the auditing tool looks like. It's a simple CLI and we're going to release it on NPM
and as a binary soon. As of today, you need to clone the repository.

The Apollo Federation Audit!{/* eslint-disable-line mdx/remark */}

As you know, The Guild has open source nature in its core. What we do we share, we open source, we
give away for free. It was always like that, it won't ever change.

Over the years we encountered a lot of aspects of Apollo Federation when working on query planning
for Hive Gateway (previously GraphQL Mesh, just a reminder that it's not a new project, but rather
well established).

We spent quite a few months, writing down our knowledge about Apollo Federation, in form of 40
supergraphs, covering wide range, if not all, of the spec.

Each of those supergraphs, have a set of subgraphs running as real GraphQL APIs, with real runtime
and real data.

We have created 170 tests in total so far…

All that effort to measure how compatible our gateway is with Apollo Federation... and now we give
it away to everyone, even our “competitors”, for free, no strings attached!

We never had a tool to measure gateway's compatibility with Apollo Federation, but now we have one
— and we've put it to the test!

Visit the audit page and see the results:
https://the-guild.dev/graphql/hive/federation-gateway-audit

The main reason behind building such tool, was to improve our Hive Gateway, have a set of tests we
can use for various of ways. We were also curious how well the rest of the GraphQL gateways perform,
how compatible they are, how good their query planning understands Apollo Federation. The results
are interesting.

About the Audit{/* eslint-disable-line mdx/remark */}

The existing GraphQL Gateway benchmarks focus on performance, pure speed, query planning overhead
and related factors. You only care about performance, if the gateway can query data correctly. Who
wants a fast, but partially broken gateway? All the gateway implementors knows that, and they work
hard to improve their gateway every day.

We wanted to push the community forward, by giving them a chance to make a giant jump.

That's why the auditing tool is fully open-source (MIT license), and available for everyone.

Visit the repository:
https://github.com/the-guild-org/graphql-federation-gateway-audit

We want to turn our effort into helping potential users of GraphQL gateways to better understand
what Apollo Federation support means, but also the maintainers of those gateways to improve their
score and learn from our experience.

We aim to make it a shared effort, an "official" auditing tool for Apollo Federation gateways.

Building Type-Safe Random GIF Generator with feTS

TheGuildBot — Thu, 02 May 2024 13:14:39 +0000

This article was published on Thursday, May 2, 2024 by Tuval Simha @ The Guild Blog

Embarking on my journey as a developer, I sought a project that would not only be educational but
also enjoyable. As a junior developer, I encountered the challenges of working with REST APIs,
particularly the lack of type safety. This led me to explore feTS, a tool designed to simplify REST
API development, offering type safety, efficiency, and seamless integration with TypeScript and
OpenAPI.

Exploring feTS: Elevating Type Safety in REST API Development

feTS, derived from 'Fetch' and 'TypeScript,' emerged as a game-changer in the realm of REST APIs. By
leveraging TypeScript and the OpenAPI specification, feTS ensures clarity in data exchange between
the client and server, significantly reducing errors during development. This blog post delves into
a practical example – building a Random Gif Generator – to showcase how feTS transforms the
development experience.

Building a Random Gif Generator

Step 1: Getting Started with Giphy API

To demonstrate the power of feTS, let's create a Random Gif Generator using the Giphy API. Begin by
obtaining a free API key from the Giphy developer portal here.

Step 2: Integrating OpenAPI Definitions into TypeScript

Incorporate the Giphy API's OpenAPI definitions into a TypeScript file, exporting them with the as
const modifier for strong typing. This integration ensures seamless cooperation with feTS. You can
find the Giphy OpenAPI definitions here.

Step 3: Installing feTS and Creating a Client

Install feTS using your preferred package manager and create a client using the createClient
function. The client instantiation involves providing the normalized OpenAPI types and specifying
the Giphy API endpoint.

import { createClient, type NormalizeOAS } from 'feTS'
import openAPIDoc from './openapi'

export const client = createClient<NormalizeOAS<typeof openAPIDoc>>({
  endpoint: 'https://api.giphy.com/v1'
})

You can find the complete OpenAPI definitions for the Giphy API
here

Step 4: Building Endpoints with feTS

export async function fetchRandomGif() {
  const response = await client['/gifs/random'].get({
    query: {
      api_key: 'YOUR_API_KEY_HERE'
    }
  })

  const gifData = await response.json()

  return gifData
}

Step 5: Utilizing the Gif Data

Now, you can easily use the fetchRandomGif function in your application to obtain random gif data.
Leverage the type safety provided by feTS to ensure accurate handling of the API response.

import { useQuery } from 'react-query'
import { fetchRandomGif } from './feTS/endpoint'

function App() {
  const { data, isLoading, error } = useQuery('randomGif', fetchRandomGif)

  if (isLoading) {
    return <div>Loading...</div>
  }

  if (error) {
    return <div>Error: {error.message}</div>
  }

  return (
    <div>
      <img src={data?.data.image_url} alt="Random Gif" />
    </div>
  )
}

export default App

Advantages of feTS in Gif Generator Development

Clarity in Development

feTS simplifies endpoint definitions, making API navigation clear and straightforward. The
structured interface enhances collaboration and understanding among developers.

Speedy Implementation

With feTS, manual response parsing becomes a thing of the past. Auto-generated API clients and
TypeScript types accelerate the development process.

Type Safety at Its Best

Enjoy robust type safety throughout the development cycle. feTS catches potential issues at compile
time, ensuring a reliable and error-free application.

Conclusion: Elevating Gif Generator Development with feTS

Building a Random Gif Generator using feTS exemplifies the tool's prowess in enhancing type safety,
clarity, and efficiency in REST API development. By adopting feTS, developers can create
applications with confidence, focusing on features rather than worrying about type-related
challenges.

![Demo](https://the-guild.dev/blog-assets/building-random-gif-generator-with-fets-and-giphy/gif.gif)

As you embark on your journey with feTS, remember that it's not just a tool; it's a paradigm shift
towards seamless and elevated REST API development. Happy coding!

The full code for this Random GIF Generator example is available on
GitHub, and live demo can be found
here.

GraphQL Request Cancellation in JavaScript

TheGuildBot — Mon, 29 Apr 2024 07:33:49 +0000

This article was published on Monday, April 29, 2024 by Laurin Quast @ The Guild Blog

Canceling in-flight requests in an application if a user navigates away from a view has become a
standard in modern applications. GraphQL client libraries such as Apollo Client and urql support
this by default. But is it also possible to cancel ongoing logic on the server if the client stops
the request?

`AbortController` and `fetch` on the Client {/* eslint-disable-line mdx/remark */}

After the introduction of the
fetch API, sometime later we also
got the AbortController API.
These both in combination made HTTP request cancellation logic straightforward.

In the following React code snippet, we implement a React hook that uses fetch for fetching some
data using the useEffect hook. The fetch call receives the AbortSignal from an
AbortController . Within the cleanup function returned from useEffect, that is invoked when the
component containing this hook unmounts, the request is aborted via the call of the abort method
on the AbortController.

```tsx filename="React AbortController example"
function useProfileData() {
const [state, setState] = useState()

useEffect(() => {
const controller = new AbortController()
async function fetchData() {
const response = await fetch('/graphql', {
method: 'POST',
body: JSON.stringify({ query: '{ me { id name } }' }),
headers: { 'Content-Type': 'application/json' },
signal: controller.signal
})
const data = await response.json()
setState(data)
}

fetchData().catch(err => console.log(err))
return function onUnmount() {
  controller.abort()
}

}, [])

return state
}




When checking the network tab within the browser, we can see that the request was canceled.

<Callout>
  **Note:** When a pending fetch request is canceled, the Promise returned from the fetch call will
  reject with a [`DOMException`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException)\`. It
  is recommended to always add a catch handler for your fetch calls to avoid unhandled promise
  rejections.
</Callout>

All modern GraphQL clients use this under the hood for optimizing the user experience, as it is
unnecessary to load data that is no longer needed, e.g. because the user navigated away to another
view. This is especially true for devices where low data/roaming usage is desired.

## Isomorphic APIs

One of the great things about JavaScript is that APIs that were formerly exclusive to browser
environments are finally being added to various server-side runtimes. Whether Bun.js, Deno or
Node.js, all of them support both the `fetch` and `AbortController` API in recent versions!

| Runtime | fetch              | AbortController    |
| ------- | ------------------ | ------------------ |
| Node.js | ✅ (since v18.0.0) | ✅ (since v15.4.0) |
| Deno    | ✅ (since v1.0.0)  | ✅ (since v1.0.0)  |
| Bun     | ✅ (since v1.0.0)  | ✅ (since v1.0.0)  |

This enables us to run the exact same code from the client example on our server.

In addition to `AbortController` now being able on the server, all kind of libraries that do
asynchronous tasks such as IO, can similarly to the `fetch` API accept an `AbortSignal` option for
canceling any pending work in case the calling code is no longer interested in the result. An
example of this could be that a request from the client has been canceled and the server no longer
needs to load all the data and construct a response as requested previously.

## Cleaning up Resources and Pending Tasks Is Hard

While this is not particularly true for all programming languages, JavaScript servers are by default
single-threaded and no new thread or worker process is spawned for every incoming HTTP request.
Thus, we can not simply kill a thread or worker process that is performing some work in case the
request got aborted.

Because of that, cleaning up resources and canceling pending tasks is a cumbersome task that is left
to the user instead of being performed through magic.

On top of that a lot of tooling and libraries, yet need to catch up and provide the APIs (e.g. pass
`AbortSignal`) to allow cleaning up resources.

Some examples (on the server in case of an aborted client request):

*   Abort a non-transactional, expensive, and long-running SQL query (or query/read on any other
    database)
*   Abort pending HTTP requests to third-party services for fetching some data
*   Abort the GraphQL execution and stop the resolver waterfall calls for resolving all the data
    specified by the GraphQL operation sent by the client

The latter point is a superset of the two former points, as in most cases within the GraphQL
execution, the business logic as called within or specified in your resolvers will result in a
variation of reads from remote services or databases.

A good enough solution for many people could be to only have the latter and only further optimize
for the former two points when additional performance gains are justified.

## How GraphQL Execution Cancelation Works

When a GraphQL operation is sent to the server, the server will start executing the operation by
calling the resolver functions as specified by the GraphQL operation selection set. Some resolver
functions are light and will just read a property from an object, whereas others will call a remote
service or database.

Here is an example GraphQL operation causing the server to call several services in sequence.

```graphql filename="Example GraphQL Operation"
query Profile($userId: ID!) {
  user(id: $userId) {
    id
    name
    avatar {
      id
      url
    }
    posts(first: 10) {
      edges {
        node {
          id
          title
          body
          likeCount
          comments(first: 5) {
            edges {
              node {
                id
                body
                author {
                  id
                  name
                  avatar {
                    id
                    url
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

Here is a simplified view of what kind of operations will be performed as the resolvers are called.
The arrows indicate what action and resolver will be executed after another one has finished. For
simplification, we only show the resolvers that are performing IO operations.

```mermaid
flowchart
  id1["Load user (Query.user)"]
  id21["Load user avatar (User.avatar)"]
  id22["Load user posts (User.posts)"]
  id31["Load total post likes (Post.likeCount)"]
  id32["Load comments for each post (Post.comments)"]
  id4["Load author for each comments (Comment.author)"]
  id5["Load author avataer for each comment author (User.avatar)"]

  id1 --> id21
  id1 --> id22
  id22 --> id31
  id22 --> id32
  id32 --> id4
  id4 --> id5
```

So given the above operation, if the client cancels the request at the stage
`Load user posts (User.posts)`, there is no need for the server to perform all the resolver calls
and data-fetching happening after that point. Furthermore, event the pending
`Load user posts (User.posts)` call could be canceled.

```mermaid
flowchart
  id1["Load user (Query.user)"]
  id21["Load user avatar (User.avatar)"]
  id22["Load user posts (User.posts)"]
  id31["Load total post likes (Post.likeCount)"]
  id32["Load comments for each post (Post.comments)"]
  id4["Load author for each comments (Comment.author)"]
  id5["Load author avataer for each comment author (User.avatar)"]

  id1 --> id21
  id1 --> id22
  id22 -- client request cancel --> id31
  id22 -- client request cancel --> id32
  id32 --> id4
  id4 --> id5

  classDef opacity opacity:0.5
  class id31,id32,id4,id5 opacity
  linkStyle 2 opacity:0.5;
  linkStyle 3 opacity:0.5;
  linkStyle 4 opacity:0.5;
  linkStyle 5 opacity:0.5;
```

## Why We Forked GraphQL.js

GraphQL.js is the reference implementation of the GraphQL specification. GraphQL.js is also the
GraphQL engine that is used by almost all JavaScript GraphQL servers that exist today.

The reference implementation serves as a proofing ground for new features (e.g. the `@stream` and
`@defer` directives). However, there is one major drawback with GraphQL.js. Things generally move
slow and the process of testing new features and provide feedback is cumbersome as you will have to
maintain your own fork. If you want to test out multiple newly proposed features at the same time,
it gets even more complicated. We wanted to take that burden from GraphQL server builders!

When we revived Yoga Server, we wanted to make in-progress “GraphQL specification” features easily
accessible. That is why we forked GraphQL.js and now maintain this fork, where new features can be
enabled via flags.

This also allowed us to add support for passing `AbortSignal` for the GraphQL execution, which
allows canceling the GraphQL data resolving waterfall in case the incoming request got canceled.

## How to Enable GraphQL Execution Cancelation in GraphQL Yoga

Execution cancellation is not yet a feature that is enabled by default as we are still gathering
intel on its behavior in a real-world environment (on our [Hive](https://the-guild.dev/graphql/hive)
GraphQL API).

For now, opting into this feature is achieved via a plugin.

```ts filename="GraphQL Yoga cancelation plugin"
import { createYoga, useExecutionCancellation } from 'graphql-yoga'
import { schema } from './schema'

// Provide your schema
const yoga = createYoga({
  plugins: [useExecutionCancellation()],
  schema
})

// Start the server and explore http://localhost:4000/graphql
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})
```

After that, you should immediately benefit from GraphQL execution cancellation without having to do
any further optimizations.

Depending on whether you are performing other advanced GraphQL optimizations such as data-fetching
lookaheads or similar, you might also want to implement `AbortSignal` propagating in those API
surfaces. For that, we recommend reading the
[Yoga documentation on GraphQL execution cancellation](https://the-guild.dev/graphql/yoga-server/docs/features/execution-cancellation).

## Conclusion

HTTP request and database read cancelations are powerful tools that can be handy when encountering
performance problems for often aborted paths.

Similarly, aborting the GraphQL execution can potentially free up a lot of resources otherwise
wasted for fetching data and constructing a response that is no longer needed.

Writing cancelation logic for HTTP requests and database read cancelation can be cumbersome, but
implemented via an abstraction layer if needed.

Yoga server is a powerful JavaScript runtime agnostic GraphQL Server that supports GraphQL execution
cancellation.
[You can learn more here](https://the-guild.dev/graphql/yoga-server/docs/features/execution-cancellation).

If you are facing related or other issues with GraphQL APIs, feel free to reach out! We offer a wide
range of services and are experts in building and maintaining GraphQL API tooling.

The Guild - Rebranding in open source

TheGuildBot — Sat, 24 Feb 2024 14:30:30 +0000

This article was published on Saturday, February 24, 2024 by Uri Goldshtein @ The Guild Blog

TL;DR

The Guild never had a marketing, design or branding function
As we see our tools as best of breed in any category we work in, we want to get more exposure to it on our ecosystem
We've also want more open source developers to know you can create open source businesses in a sustainable way, like we have successfully managed to do
We've decided its time for The Guild to go through a professional process of branding and marketing
We've hired experts to help us in that process - North Star
Like everything we do at The Guild - we've decided to take the whole process open source and share with our community everything in the process, including our wins and painful points

The Guild Today

We are a group of developers, creating open source, developer experience and infrastructure tools
for managing data and APIs.

We've managed to create industry leading tools, that are fully open source, while still being very
profitable with solid financials that makes us resilient for the future.

The whole structure of the group was to make sure we can create tools everyone can rely on for the
very long term.

We've also managed to become a really interesting place for ambitious developers to work in - all of
our libraries are under developer's names and not under The Guild's org, in order to give the
developers the fully power and credit they deserve.

Building on all of these foundations together, we believe we've managed to create a strong ground
for building quality software and we want to inspire others to create long term, quality software
instead of short term, trend and marketing based software foundations.

We've had a unique vision and a way to achieve it and we've managed to be successful at it.

At this stage, we feel that more people should be aware of what we do.

Some as users of our tools and some as other open source developers and solution providers, to share
our tools and learnings with the wider community.

We have never done any marketing and we think this is a good time to start - At this stage,
marketing to us is a force for bringing awareness to ideas we believe in

Where We Want to Be, Our Goals from the Process

As we go through the process, we have to ask ourselves what do we actually want to get.

Our current goals as we see them today:

Clear offering: We offer many products, spread across many places across the stack. It is currently very hard for someone new to The Guild's ecosystem to understand what each tool does and how it could benefit them

This might seem slightly confusing...

Philosophy of development: We've managed to create a philosophy around how we work, in order to create sustainable, reliable, quality open source infrastructure. We want to share these ideas with our users and other open source developers
Hiring: We want to give ambitious open source developers a career path that they are not currently getting in other companies. Maximizing their individual potential is the core reason of why we've created The Guild in the first place. We want to let developers know that The Guild is more than a GraphQL provider and it's also more than an API provider — it's the open source company, structured around the most solid solutions in open source that could be relied upon by users and tool builders - More exposure: More developers to be aware of the available products we offer and why they are the best in the industry (if they are not, we want to understand why as part of that process, we want to share that as well in public). That includes the GraphQL ecosystem but also the wider API ecosystem

The Process

Here is the process we'll go through, led by North Star (they've also
wrote about the process
here):

First Phase — Brand Audit

During that process, North Star will analyse the current state of The
Guild

They will learn about:

How we communicate
Our current brand and identity
Our value propositions
The overall ecosystem

We will share the full analysis results with the community.

We believe this would be helpful as we could get feedback from all of you about the results and if
we got it right.

Also, the fact that the evaluation of the ecosystem would be open source, could help other vendors,
including direct competitors of ours, to get a clear picture of the current landscape, what is
strong and what is missing. Also, If we get something wrong about them, they could contribute to the
report!

That same analysis could help solution providers and architects at companies to take more informed
decisions on which tools to choose for the future of their companies.

We can do it because we have the freedom to choose to use our competition when they are better. We
can stop developing something and contribute to another existing solution if we don't see the
benefit in our solution, thanks to our unique structure.

In the world of open source, we believe that ‘competition' is not a harsh business reality. Rather
than that, it is the collective effort towards building the best solutions that push the whole
industry forward. And, of course, a personal motivation for growth!

Second Phase — Diagnostics

During this phase, we'll diagnose our current brand identity. While all of us at The Guild have
their own beliefs about the company, it's very important to us to see how you perceive us, so that
we get as much user perspective as we can!

We'll also take a look at other great companies in this space, to find inspiration and best
practices.

The diagnostics phase will aim to be as collaborative with the community as possible, as we want to
challenge our own assumptions and find the most quality feedback!

Third Phase — Strategy

Once we have a complete and data-driven understanding of the current state of The Guild, both from
our internal perspective and external, with the help of our community, we'll be able to move towards
building a set of strategic foundations.

We will be hosting a workshop with North Star, during which we'll work together and decide how we
want to tackle our goals and what are the best tactics to accomplish those.

We are still thinking about the best ways to make that process also open source and collaborative
with the community.

Fourth Phase — Creative Execution

Once we decide on the full strategy, we're going to execute on it — also here in an open source
manner.

All of our websites are already open source, so each change we'll make there would be as well.

But we also want to open source our brand assets, design system in Figma and frontend components,
communication strategy and guidelines and any other product or marketing related work we'll execute
on.

Usually these processes are not being done in the open, even at open source companies.

We'll need to use or create tools and ways that help us collaborate on the process in that unique
way. We hope others could benefit from that as well and maybe make it easier for companies to go
through these types of processes in the open.

Why Are We Sharing All of It in the Open?

The Guild was created to be a place where solutions that are sustainable and for the long term are
being built.

One of the best ways to accomplish that is to be fully open source. It means that no matter what
happens, including anything with the company itself — the solutions and the code are still
available, out there and anyone could use and build upon them.

As we've successfully managed to create that environment, it also came with a great deal of freedom.

For example, we could have our most successful product -
GraphQL Hive - to be
fully open source! While still
being extremely successful SaaS business.

That freedom drives us to work on things in the best way possible and we believe that sharing the
marketing and branding process with all of you, will help us achieve the best results.

It would help others who want to go through similar process, it will give access to our community to
influence and take part in this important process and it would help other GraphQL vendors and push
the whole ecosystem forward!

A Call for All of You

Like open source tools - the most all of you will get involved, share your opinion and maybe even
contribute - The Guild will become a better place and a powerful community for your needs.

We will be sharing every step of the way here, on our blog. During the journey, we'll also be asking
you to bring your thoughts and ideas in. They're most welcome!

Announcing Accounts.js 1.0 Release Candidate

TheGuildBot — Mon, 08 Jan 2024 09:21:14 +0000

This article was published on Monday, January 8, 2024 by Niccolo Belli @ The Guild Blog

The first release candidate of Accounts.js 1.0 is now officially
available!

It's the culmination of a long process of rearchitecting the whole framework, which is finally a
first-class citizen of the graphql-modules package. It
supports the latest GraphQL.js v16 and graphql-tools v10 as
well as any modern GraphQL server including Apollo Server v4 and
GraphQL Yoga v5.

About Me

My name is Niccolò Belli, darkbasic on GitHub. I'm a freelance
full-stack web developer passionate about open source who loves to work with Typescript and GraphQL,
along with managing Linux servers. I've been working on Open Source technologies since many years
and I've recently become an Accounts.js maintainer because I was tired of the existing alternatives
and their lack of GraphQL integration. While I don't like overly-opinionated frameworks that lock
you in into their ecosystems I love to work with libraries that allow you to quickly prototype your
application while being scalable and highly customizable. That's why I'm also a MikroORM
collaborator, which is the best Node.js ORM available and allows me to retain any amount of
flexibility if I decide to manually write big PostgreSQL queries and hydrate the results back into
the ORM for further processing. I've developed many tools around this workflow, including
automatically generating slonik types via the ORM metadata to
manually write composable SQL queries that are type safe at runtime and build time. This is material
for another blog post but I would love to make everything open source once my prerequisite
zod PR gets merged.

What Is Accounts.JS

The @accounts suite of packages aims to provide an end-to-end authentication and accounts
management solution with n user-friendly way to start while preserving options for configuration.
These packages offer OAuth support for popular providers such as Instagram or Twitter, two-factor
authentication, password-based accounts, recovery options, and customizable account creation and
validation.

To integrate accounts-js into your application, you need to configure these three components:

Transports: The flexibility of accounts-js allows it to be integrated with different types
of APIs. For now, we provide packages for both GraphQL and REST.
Databases: Accounts.js provides a
native Mongo integration.
Additionally, it offers
MikroORM and
Typeorm
integrations, which lets you use accounts-js with any database. Optionally, you can use Redis
to store the session data, or provide a custom database adapter that will work with existing
authentication strategies by implementing the DatabaseInterface.
Strategies: You can use multiple strategies to let your users access your app. For now, it
supports password-based, magic link, and OAuth authentication methods.

Note: Accounts.js is a full-stack solution, providing a full set of packages to seamlessly
implement your chosen authentication workflow on the client as well!

The New Architecture

In Accounts.js 1.0, we use graphql-modules to compose the authentication framework, automatically
piecing together your preferred database adapter(s) with the authentication service(s) of your
choice (password-based, OAuth, etc). As mentioned before, accounts-js currently supports GraphQL
and REST. For the former, graphql-modules automatically provides the schema based on the modules
you're using, while for the latter, it provides dependency injection across the various modules to
piece them together.

const app = createApplication({
  modules: [
    createAccountsCoreModule({ tokenSecret: 'secret' }),
    createAccountsPasswordModule({
      requireEmailVerification: true,
      sendVerificationEmailAfterSignup: true,
    }),
    createAccountsMongoModule({ dbConn }),
  ],
  schemaBuilder: buildSchema({ typeDefs, resolvers }),

If your application already uses graphql-modules, all you need to do is add the accounts.js
modules of your choice to your own application module. Otherwise, it's a matter of providing your
resolvers and type definitions to the buildSchema function.

// GraphQL Yoga 5
const yoga = createYoga({
  plugins: [useGraphQLModules(app)],
  context: ctx => context(ctx, { createOperationController })
})
createServer(yoga).listen()

// Apollo Server 4
const apollo = new ApolloServer({
  gateway: app.createApolloGateway()
})
startStandaloneServer(apollo, {
  context: ctx => context(ctx, { createOperationController })
})

At this point, whatever your GraphQL server of choice, your authenticated application is just a few
lines of code away.

But what if all I care is REST?

Use the graphql-modules injector to retrieve the AccountsServer instance and feed it to
@accounts/rest-express!

const controller = app.createOperationController({
  context: {}
})
const accountsServer = controller.injector.get(AccountsServer)
expressApp.use(accountsExpress(accountsServer))

Alternatively, if you don't want to use graphql-modules, you can still manually instantiate the
providers. Here's
an example.

The New MikroORM Database Adapter

The second big change in Accounts.js 1.0 is the release of the brand new
MikroORM database adapter. MikroORM is a TypeScript ORM for Node.js based
on Data Mapper, Unit of Work and Identity Map patterns. It is also very well-written and actively
developed. Today also marks the release of the v6 of MikroORM, which incorporates
my recent work to automatically batch references
and collections and retrieve them via dataloaders firing a single query. This is especially useful
with GraphQL transport since it automatically solves its notorious N+1 problem without you even
noticing it—more information here.

@Entity()
export class User extends AccountsUser {
  @Property()
  firstName: string

  @Property({ nullable: true })
  lastName?: string

  constructor({ firstName, lastName, ...otherProps }: CtorArgs) {
    super(otherProps)
    this.firstName = firstName
    if (lastName) {
      this.lastName = lastName
    }
  }
}

The Accounts.js MikroORM database adapter can be backed by your database of choice (PostgreSQL,
MySQL, MariaDB, SQLite, MongoDB). It won't force you into any existing entity schema: you can use
the existing entities or provide your own, but please make sure to extend the base ones so that
authentication can occur.

entities: [
  User,
  getUserSchema({ AccountsUser, abstract: true }),
  getEmailSchema({ UserEntity: User }),
  getServiceSchema({ UserEntity: User }),
  getSessionSchema({ UserEntity: User }),
],

Under the hood, it uses MikroORM's EntitySchema, so you
must also provide the schema for the base entities.

Breaking Changes

@accounts/boost has been removed. It was no longer deemed necessary because of the new
graphql-modules architecture that already allows you to plug and play various modules. For
example, instead of providing an existing database connection, you can let @accounts/module-mongo
create a new one for you:

const app = createApplication({
  modules: [
    [...],
    // If you don't provide dbConn it will automatically
    // create a new one, but the module needs to be awaited.
    await createAccountsMongoModule(),

@accounts/graphql-api has been moved into the following packages:

@accounts/module-core
@accounts/module-magic-link
@accounts/module-mikro-orm
@accounts/module-mongo
@accounts/module-password
@accounts/module-typeorm

These packages can assemble your desired authentication workflow and your preferred database
adapter. Despite the significant changes under the hood, I strived to keep the public API mostly the
same, so migrating to 1.0 should be a manageable effort.

What's New

We switched from pnpm to yarn 4.
We now return code 401 unmasked errors when unauthorized.
Added the requireEmailVerification option to require the user to verify the email in order to be able to authenticate.
You can now enable both ambiguousErrorMessages and enableAutologin if requireEmailVerification is disabled.
@accounts/password provides express endpoints to verify the email or reset the password whenever the user clicks on the links received via email.
@accounts/rest-express now validates its inputs via express-validator.
The examples now use graphql-yoga v5 instead of the old apollo-server 2.
A new @apollo/server v4 example has been added.
A basic graphql-http example has been added.
A MikroORM example has been added.
The accounts-microservice example has been rewritten from scratch to use modern graphql-tools.
Docs have been refactored to use docusaurus-plugin-typedoc-api instead of scripts/generate-api-docs.ts.
New and much improved CI release workflow.
Basic support for running tests from vscode.
Upgraded graphql-modules to v3 alpha
Upgraded @graphql-tools/merge to v9
Upgraded @graphql-tools/schema to v10
Upgraded @graphql-tools/utils to v10
Upgraded graphql to v16
Upgraded typeorm to 0.3.17
Upgraded @apollo/client to 3.8
Upgraded @graphql-codegen to v5
Upgraded mongodb to v6
Upgraded ioredis to v5
Upgraded jsonwebtoken to v9
Upgraded lodash to 4.17
Upgraded pg to 8.11
Upgraded request-ip to 3.3
Upgraded oauth to 0.10
Upgraded node-fetch to 2.7
Upgraded express to 4.18
Upgraded emittery to 0.13
Upgraded @levminer/speakeasy to 1.4
Upgraded @graphql-tools/delegate to v10
Upgraded @graphql-tools/stitch to v9
Upgraded @graphql-tools/wrap to v10
Upgraded mongoose to v8
Upgraded react to 18.2
Upgraded jest to 29
Upgraded typescript to 5.3
Upgraded eslint to v8
Upgraded prettier to v3
Upgraded @apollo/server to 4.9
Upgraded docusaurus to v3

Remaining Work for the Stable Release

OAuth authentication, while working, surely deserves some love. While REST endpoints for OAuth
should be functional, there are no mutations or resolvers yet, meaning you can't use them with the
GraphQL transport. I'd also like to review the OAuth code and write some examples.
@accounts/oauth-instagram, in particular, still relies upon the deprecated request package and
should be updated. Other popular OAuth providers like Facebook still need to be added (but PRs
exist).

Before the 1.0 stable gets released, I plan to get the existing providers in a better shape,
together with examples and the relevant GraphQL schema.

Post 1.0

I want to create a new @accounts/phone authentication service which lets you authenticate via SMS
OTPs. That would be especially useful in react-native applications where you could automatically
read the SMS and automate the authentication process.

Currently, Accounts.js bundles CommonJS code. While CommonJS can be imported in both CommonJS and
ESM applications, that would rule out Deno/Bun support. For the same reason, we cannot use a wrapper
either: while that would allow us to use ESM imports, it wouldn't be real ESM and thus won't be
compatible. The remaining alternatives are pure ESM and dual packages. While several library authors
opted for the former because of
dual package hazard concerns, I
weigh the benefits differently. While dual package hazards are real, the whole GraphQL ecosystem
relies on dual packages; thus, using instance of is already a hazard. These authors suggest using
async imports to import their pure ESM libraries in common projects, which exposes everyone to the
same hazard (not even considering that this is only viable in async contexts). That goes against why
they decided to bundle pure ESM in the first place. I think it's still too early to target pure ESM,
and dual package is the lesser evil, so I'm leaning towards that for future releases, but I'm ready
to change my mind if you provide enough arguments.

I'd also like to implement some form of account linking, where users could link their existing
account with a different authentication service (for example, password-based and OAuth).

I want to extend Multi-Factor Authentication outside of the password service, baking it into the
core of accounts.js so that any authentication service can take advantage of it.

If future major versions of Accounts.js introduce breaking changes to the database structure, I
would like to provide migrations directly via the @accounts/mikro-orm package.

Last but not least, I would like to bake in cookies authentication. Not only would that fare better
against XSS, but it would also allow server-side rendering and thus enable the usage of frameworks
like Next.js. Alternative storage methods would remain available for those using native
applications.

At the end of the day, 1.0 is just a number, and I really want to provide stable APIs via semantic
versioning.

Accounts.js is an open-source project, and we welcome your
contributions!

Building Open Source GraphQL Security

TheGuildBot — Thu, 07 Dec 2023 23:44:52 +0000

This article was published on Friday, December 8, 2023 by Nohé Hinniger-Foray @ The Guild Blog

Open-Source GraphQL Security, Importance & Tools

Open-source principles have forged GraphQL as a standard, it's ecosystem and community. Bringing
value via transparency and collective knowledge as well as empowering the community with tools and
practices to build better, bigger & more efficient APIs from day to day. Now that GraphQL APIs are
well-established and with a lots of queries on a daily basis, ensuring their security becomes
crucial.

In this exploration, we'll dive into how these open-source practices are important and benefits for
the security of GraphQL and which community tools you can leverage today to secure your APIs.

GraphQL Is Open-Source at Its Core

The inception and evolution of GraphQL are intrinsically tied to the principles of open-source,
ensuring it flourished not just as a query language but as a community-driven initiative progressing
toward broader, unified API development standards. From its public
specifiction release in 2015 by Facebook to its
transition to the GraphQL Foundation in 2018—hosted by the Linux
Foundation—its journey has been transparent and collaborative.

While the GraphQL specification paved the way for consistent and efficient API queries, the
open-source community enhanced this original draft further. Take the
Relay Pagination Specification, for instance, which
streamlines how pagination can be handled in GraphQL (among other React specific features),
providing a standard methodology that developers can rely on. Similarly, the introduction of custom
directives allowed GraphQL to become more flexible and adaptable to specific use-cases, like the
@rest directive
or
@live queries.

Moreover, the vast majority of widespread GraphQL tools have and are being built under open-source
licences. Servers implementations, frontend clients, utilities like schema management, code
generation or even fully fledged API platforms are legion. You can find a comphrensive list of such
tools on the graphql.org website. The Guild
are also masters when it comes to GrahpQL & Open-source and their tools come highly recommended.

For instance, as GraphQL is transport agnostic, it can be used with any protocol, a tremendous
amount of open-source tools have been built to leverage this flexibility, especially by
@enisdenjo: graphql-http
graphql-ws
graphql-sse

I can also mention the work on unified APIs via
GraphQL federation that is also under active
open-source development, with the
Composite Schema Working Group initiative, and
upcoming
GraphQL Fusion
specification.

And last but not least, the GraphQL community is also very community centered, wether via the
GraphQL working group or the various
events and meetups such as the GraphQL Conf.

In essence, GraphQL isn't simply open-source in its availability but embodies open-source in its
ongoing development, enhancements, and community engagement, perpetually enriching its ecosystem
with diverse inputs, insights, and innovations.

The Importance of Open Source and Public Resources in Security

Keeping the internet safe is a big challenge. It's like a tightly connected place with lots of
potential threats. Open source and public tools have been doing a great job at protecting it for
years.

Cybersecurity thrives on collaboration, exemplified by the Common Vulnerabilities and Exposures
(CVE) system. This public database acts as a central repository for known
cybersecurity threats, allowing for quick dissemination and response. By making vulnerabilities
public, the CVE system ensures timely and widespread implementation of security measures. For
instance, the identification and patching of the Heartbleed bug in OpenSSL was significantly aided
by the CVE system, showcasing its effectiveness in promoting rapid response.

Open source plays a crucial role in cybersecurity by fostering an environment of transparency and
collaboration. It allows for the open identification and resolution of vulnerabilities, benefiting
the entire digital ecosystem. For example, the Linux Kernel, known for its security, continually
improves through community contributions. Similarly, tools like Kali Linux offer insights into
offensive cybersecurity strategies, helping developers strengthen their defenses.

This combination of open source and CVE is especially vital in areas like GraphQL and API security,
providing a foundation for robust, adaptable cybersecurity strategies. Through shared knowledge and
tools, open source and CVE create a proactive defense against evolving cyber threats.

In a field like cybersecurity, where dangers morph quickly, having shared knowledge, united
alertness, and available-to-all tools become an essential shield against potential attacks. The
marriage of open source and cybersecurity offers a lively platform for ongoing learning, changing,
and sharing attack and defense mechanisms, crafting a global, united front against cyber threats.

Moving forward, we'll dive into how this perfect pairing of open source and cybersecurity is
crucial, not just relevant, for GraphQL and API security. We'll highlight practical tools and
strategies you can use today to protect your applications.

Open Source GraphQL Security Ressources & Tools

There are many GraphQL open-source tools available to help developers and businesses defend against
possible cybersecurity threats. From defensive measures that shield sensitive data to offensive
tools aimed at identifying vulnerabilities, the open-source community has build invaluable resources
to cover a wide variedy of cyber-security needs.

Learning Tools & Resources: Armoring with Knowledge

In the sphere of cybersecurity, especially concerning GraphQL, the adage 'knowledge is power' is
paramount. Continual learning, embracing best practices, and leveraging insights from the community
is an essential shield to secure APIs against vulnerabilities.

Best Practices

*   [Persisted/Trusted queries](https://benjie.dev/graphql/trusted-documents): This feature allows
    you to save bandwidth and improve performance by sending a hash of the query instead of the
    full query. It also has a huge impact on security, as it prevents attackers from sending
    arbitrary queries to your server. Check GraphQL Yoga
    [persisted operations](https://the-guild.dev/graphql/yoga-server/docs/features/persisted-operations)
*   [9 GraphQL Security Best Practices](https://escape.tech/blog/9-graphql-security-best-practices/):
    Dive into Escape's comprehensive guide which unveils nine pivotal security best practices,
    presenting a blend of actionable insights and theoretical knowledge to fortify GraphQL
    implementations against potential threats.
*   [The Guild's best practices article](https://the-guild.dev/blog/unleash-the-power-of-fragments-with-graphql-codegen):
    While this resource by The Guild isn't strictly security-focused, it provides invaluable best
    practices on GraphQL clients that, when adeptly applied, augment the robustness and efficiency
    of GraphQL APIs, subsequently enhancing their inherent security.
*   [Official authorization docs](https://graphql.org/learn/authorization/) The official GraphQL
    documentation provides a comprehensive guide to authorization, which is a crucial aspect of
    security in your API. Generally speaking, knowing the specification and documentation is a key
    to understanding how your application works and therefore how to secure it.

API Security Academy

The API Security Academy, an open-source platform developed by Escape, navigates through the
multifaceted world of GraphQL security. A wellspring of knowledge, it offers structured learning
paths, exploring vulnerabilities, attack vectors, and preventive strategies, thereby forging a
security-savvy developer who can intuitively construct and validate secure APIs.
Blogs and More

Explore the many insights and experiences shared by experts through different channels:

*   **Blogs**: Immerse yourself in rich content through blogs from
    [Escape](https://escape.tech/blog/) and [The Guild](https://the-guild.dev/blog/), offering a
    spectrum of perspectives, learnings, and strategies around GraphQL and cybersecurity.
*   **Videos**: Discover visual insights through a collection of videos curated by
    [GraphQL WTF](https://graphql.wtf/). Although not strictly centered around security,
    understanding various facets of GraphQL enhances your capability to architect, implement, and
    secure GraphQL APIs more effectively.

Online security is always changing, often at a rapid pace. By adhering to best practices, engaging
with learning platforms and tapping into the collective knowledge shared through blogs and videos,
we arm ourselves and our APIs against the multifaceted cybersecurity threats that persist in the
digital realm.

This path of continuous learning and adaptation ensures that as developers and cybersecurity
professionals, we remain up to date to secure our GraphQL APIs against both prevalent and emerging
threats.

Defensive Tools

GraphQL Armor

Developed by our tech team at Escape, GraphQL Armor is a middleware plugin designed to be an
immediate security upgrade for your GraphQL server. Acting like a personal bodyguard for your
data, it integrates seamlessly with Envelop — a
flexible plugin system introduced by The Guild for crafting high-quality, performant GraphQL
extensions. GraphQL Armor adheres to the ethos of providing accessible, user-friendly security
solutions that can be efficiently integrated into your GraphQL setup, safeguarding it from
potential vulnerabilities and threats.
GraphQL Shield

GraphQL Shield empowers developers with a permission layer for applications, securing APIs by
utilizing an intuitive rule-API that activates the Shield engine on every request. Moreover, it
smartly caches data to keep your application sprightly and ensures internal data remains under
wraps, enhancing both performance and security.

With open-source defensive tools like GraphQL Armor and GraphQL Shield, businesses and developers
can reinforce the security of their GraphQL APIs, protecting data and operations from unauthorized
access and potential malicious activities. Navigating through the extensive open-source ecosystem
and leveraging these security tools not only fortifies your GraphQL APIs but also enriches the
collective knowledge and defense mechanisms of the community, aligning with the spirit of
collaborative development and security.

In the upcoming section, we'll delve into offensive tools and resources for learning to equip you
with a holistic arsenal for safeguarding your GraphQL APIs.

Offensive Tools: A Proactive Step towards Fortified Defense

When it comes to ensuring an unbreakable security perimeter, adopting an offensive approach is
pivotal. By putting our defenses to the test and simulating possible attacks, we preemptively expose
potential vulnerabilities and weaknesses before they can be exploited maliciously. This strategy is
basically following the idea: the best defense is a good offense. Let's uncover two powerful
open-source tools that allow us to proactively secure our GraphQL APIs by adopting an offensive
stance.

Goctopus

Say hello to Goctopus, our open-source GraphQL endpoint discovery and fingerprinting tool. This
tentacled marvel meticulously hunts down GraphQL endpoints, fingerprinting their authentication
methods and schema availability, ensuring not a single detail slips through its grasp. Built by
the Escape team, Goctopus lends developers and businesses a watchful eye, enabling them to
identify and comprehend the specifics of GraphQL endpoints with precision, ensuring that they
can reinforce any possible points of vulnerability within their organization before they become
a target.
Clairvoyance

Meet Clairvoyance, a savvy tool designed to peek into GraphQL APIs even when introspection is
disabled, which is a common security measure (e.g.,
Apollo Server automatically disables introspection in production environments).
Clairvoyance subtly and skillfully retrieves schema information from these APIs, providing
developers with insights into the API structure and potential vulnerability points. This becomes
particularly vital when dealing with APIs that have sought to shield their schema details as a
security measure.

Both Goctopus and Clairvoyance offer distinctive capabilities, allowing developers and cybersecurity
professionals to proactively and meticulously assess and bolster their GraphQL API defenses. By
utilizing these offensive tools, we position ourselves a step ahead, ensuring that our APIs are not
just constructed with security in mind but are continually assessed and enhanced to defend against
evolving cybersecurity threats.

As we move forward, our journey will venture into open-source learning resources and best practices
in GraphQL security, ensuring that your armory is not just stocked with tools but also with
knowledge and strategies to implement them effectively.

Wrapping up and Joining Forces

Huge shoutout to The Guild for hosting this dive into the depths of
GraphQL and open-source magic. Their work, and the work of countless others in our robust community,
propels GraphQL to new heights daily. Your code, knowledge, and keen eyes are the gears moving this
ecosystem forward.

But hey, let's not stop there! Contribute, Engage, Elevate. That's the open-source mantra. Your
expertise could well be the next big leap forward for GraphQL tools and platforms. Check out these
awesome GraphQL projects on graphql.org/code and the
Awesome GraphQL security list!
Here at Escape, our open-source initiatives and SaaS solutions are all about
injecting the GraphQL space with robust, unshakeable security defenses. But it's a team sport, and
every contribution counts.

Let's keep the momentum, elevate our game in cybersecurity, and shape a future where GraphQL isn't
just powerful and efficient but an unassailable fortress in API development.

Thanks for tagging along on this adventure. Together, let's build a safer, and better GraphQL
ecosystem.