DEV Community: Hasura

The complexity of building a GraphQL API permissions layer and how Hasura solves this

Hasura — Wed, 05 Jul 2023 09:17:26 +0000

Introduction

API security breaches are on the rise. Gartner predicts that by 2025, insecure APIs will account for more than 50% of data theft incidents. As enterprises continue to embrace an API-driven approach to software development (for all the benefits it brings), arming their developers with the tools to build secure APIs with proper data access and authorization logic needs to be a priority.

Building an authorization layer involves many factors. In GraphQL, authorization belongs in the business logic layer and not typically inside resolvers. It is more complex to write an authorization layer for GraphQL APIs than REST APIs. In this blog, we will see what it takes to build authorization logic for a DIY GraphQL server to understand how it is more complex. We will also compare it with Hasura and how it solves this complexity by being declarative and leveraging predicate pushdown.

Here's a quick TL'DR and summary before diving deep into this post.

Key items to consider

Data modeling

Data models contain key information about the types of data, relationships between data. This is used to determine the kind of authorization system that needs to be built.

For example, you have users of the application that can view public data of all users and certain private data of them. The data model now contains certain table columns relevant to this and also relationships that are relevant to this private data.

Roles and attributes

The common ways to model your authorization system is through RBAC (role-based access control and ABAC (attribute-based access control).

You could start defining roles for the application and list out use cases and privileges for each. RBAC could be flat, hierarchical, constrained and symmetrical. Authorization can also be modeled based on attributes where the user who logs in to the application will have certain attributes (type of user, type of resources, and the environment in which they are accessing) that can be checked for allowing access.

Nested rules

The GraphQL schema may or may not be a direct map to the data models. In some cases, the data model extends to multiple data sources. Even within the same data source, the GraphQL query could be nested with multiple fields spanning relationships. Applying authorization logic contextually to the nested query is vital.

For example:

query {
  users {
    id
    name
    orders { // apply permission rule here too
      id
      order_total
    }
  }
}

Here the orders is part of the users relationship and is nested. But the authorization logic needs to apply for both users, for orders, and for any level of nesting of the query, contextually.

Performance

Ideally, authorization checks shouldn’t add a lot of overhead to the response latency. In reality, when you are writing a custom GraphQL server yourself, checks are done after the data fetching operation and there’s a lot of unnecessary data fetched, which slows down the database if you consider millions of requests which slows down API performance as a result.

Predicate pushdown

If the authorization logic is heavily dependent on the data being fetched, it is important to do a predicate pushdown of the Authorization rules.

For example: If you are fetching orders placed by a user on an e-commerce app, you need to be able to apply the rule in the query that goes to the database to fetch only the orders placed by the user requesting them. This is not only faster, but also the most secure way to apply authorization logic.

Building a DIY authorization layer for a GraphQL API

You can build an AuthZ layer using middleware libraries. The maturity of AuthZ libraries in GraphQL depends on the language or framework you are in.

Why is building an authorization layer complex?

When you are writing your own GraphQL server with custom authorization rules, there are a number of methods to write this logic, depending on the use case. You have:

API-wide authorization
Resolver-based authorization
Schema / model-based authorization

The resolver-based authorization quickly balloons into a lot of boilerplate code if authorization rules are applied to every field. Even with repeated rules and patterns that can be applied, it can easily expand to thousands of lines of code to secure your application. And this code becomes difficult to maintain.

In the schema-based authorization, the authorization logic is dependent on the GraphQL schema and becomes independent of the underlying database or data fetching libraries and ORMs.

Authorization in GraphQL is typically built using _ Context _ object that is available on every request. The context is a value that is provided to every resolver and is created at the start of a GraphQL server request. This means you can add authentication and authorization details to the context, such as user data.

Here’s how a typical AuthZ context gets passed in a DIY GraphQL Server written in Node.js:

Parsing and validating JWT token

The first step is to parse and validate the incoming JWT token. Once the JWT token is verified, you can pass it to the context. We are using JWT tokens as an example here, because it is universal and works across platforms.

An example request:

Endpoint: myapp.com/v1/graphql

Headers: Authorization:

The Authorization header is parsed, validated, and verified. The underlying authentication service used could be any solution that issues JWT. Here’s some example code that verifies a JWT token:

try {
    if (token) {
        return jwt.verify(token, YOUR_SECRET_KEY);
    }
    return null;
} catch (err) {
    return null;
}

Here’s an example taken from a DIY GraphQL Server (Apollo) to parse the context:

Create a new instance of Apollo Server by passing in the type definitions and resolvers.

const server = new ApolloServer < MyContext > ({
    typeDefs,
    resolvers,
});

Create a standalone server that retrieves the token from headers and returns the user information as context.

const {
    url
} = await startStandaloneServer(server, {
    // Note: This example uses the `req` argument to access headers,
    // but the arguments received by `context` vary by integration.
    context: async ({
        req,
        res
    }) => {
        // Get the user token from the headers.
        const token = req.headers.authorization || '';
        // Try to retrieve a user with the token
        const user = await getUser(token);
        // Add the user to the context
        return {
            user
        };
    },
});

Passing context

Once the token is extracted, you need to pass the context object to every resolver that will get executed. Now all of your resolver code gets access to the context.

In the above example, we can see that the user data is passed to the context.

API-wide authorization

There are a few rules that might need to be enforced at the request level, even before passing it on to the GraphQL resolvers.

For example, you could block a user from performing any queries and return a 401, unauthorized error. Again, this involves code logic and the logic could become a lot of boilerplate if there are many rules.

Resolver-level authorization

As the context gets attached to each resolver, it is now possible to authorize the request inside the resolver. This method is only suitable for basic authorization logic when there are only few resolvers and few rules to check and authorize users.

For example: You have a users field that returns a list of user names. You will end up writing code, which looks something like this:

users: (parent, args, contextValue) => {
    // In this case, we'll pretend there is no data when
    // we're not logged in. Another option would be to
    // throw an error.
    if (!contextValue.user) return null;
    return ['bob', 'jake'];
};

The contextValue is now available for parsing and authorizing the user.

Note: This is resolver logic for one field. Imagine repeating logic code in every single resolver and field. It is very challenging to scale this. It is also very challenging to update any logic quickly.

GraphQL schema-based authorization

In a large schema with plenty of data based authorization, there are patterns of rules that are applicable for multiple queries. For example: Allow the user to fetch their own data and not any one else.

Here’s an example from GraphQL AuthZ library using schema as a data source.

// using schema as a data source inside pre-execution rule
const CanPublishPost = preExecRule()(async (context, fieldArgs) => {
    const graphQLResult = await graphql({
        schema: context.schema,
        source: `query post($postId: ID!) { post(id: $postId) { author { id } } }`,
        variableValues: {
            postId: fieldArgs.postId
        }
    })
    const post = graphQLResult.data?.post
    return post && post.author.id === context.user?.id
})

If you look at the return statement at the end in the above code snippet, that’s where the logic of checking user ID is written.

How does Hasura’s authorization layer work?

Hasura has a powerful authorization engine that allows developers to declaratively define fine-grained permissions and policies to restrict access to only particular elements of the data based on the session information in an API call.

Implementing proper data access control rules into the handwritten APIs is painstaking work. By some estimates, access control and authorization code can make up to 80% of the business logic in an API layer. Securing GraphQL is even harder because of the flexible nature of the query language. Hasura radically simplifies the effort needed to build authorization logic into APIs.

Declarative

With Hasura, you can transparently and declaratively define roles, and what each role is allowed to access in the metadata configuration. This can be done either through the Hasura Console or programmatically through the Hasura CLI. This declarative approach to authorization is simpler to create, maintain, evolve, and audit for developers and security teams.

Fine-grained access control

Hasura supports a role-based access control system. Access control rules can be applied to all the CRUD operations. You define permissions granularly on the schema, sessions, and data (table, row, and column).

For every role you create, Hasura automatically publishes a different GraphQL schema that represents the right queries, fields, and mutations that are available to that role. Every operation will use the request context to further apply permissions rules on the data.

Authorization rules are conditions that can span any property of the JSON data graph and its methods:

Any property of the data spanning relationships. Eg: Allow access if “document.collaborators.editors” contains “current_user.id3⁄4
Any property of the user accessing the data. Eg: Allow access if accounts.organization.id is equal to current_user.organization_io
Rules can mask, tokenize, or encrypt portions of the data model or the data returned by a method and are labeled. These labels are called "roles."

Easily integrate with your authentication system

Authentication is handled outside of Hasura, and you can bring in your own authentication server or integrate any authentication provider that supports JSON Web Token (JWT). If your authentication provider does not support JWT, or you want to handle authentication manually, you can use webhooks.

"By using Hasura, we cut the development time in half and built our product in three months. The built-in role-based authorization system made it easy to secure our data."

Mark Erdmann, Software Engineer, Pulley

Predicate pushdown

Hasura automatically pushes down the authorization check to the data query itself, which provides a significant performance boost and cost savings by avoiding additional lookups and unnecessary data egress, especially at larger scale.

Hasura automates predicate pushdown, since it is essentially a JIT compiler that can dynamically apply the filter in where the clause of a SQL query is based on the user running the query. Most GraphQL server frameworks require you to write plenty of boilerplate code to achieve the predicate pushdown authorization check.

Cross-source authorization

Hasura integrates authorization rules based on data and entitlements in different sources. Hasura forwards the resolved values as headers to your external services, which makes it easy to apply authorization rules in your external service. Again, this is made possible by Hasura’s declarative authorization system.

OWASP Top 10

OWASP is most famous for the “Top Ten” framework for structuring secure applications. As the industry expands into a microservice-driven approach, it’s important for organizations to validate all of their dependencies according to the OWASP framework.

Hasura’s security-first approach ensures that the Top 10 security features and criteria are fulfilled. Read more: How Hasura addresses the OWASP Top 10 concerns.

When you are building your own GraphQL server and writing authorization logic, you will need to ensure that the Top 10 concerns are handled to be secure and compliant.

Try out Hasura

Sign up to start your journey with Hasura Cloud today. If you are an enterprise looking to learn more about how Hasura fits in your app modernization strategy, reach out to us through the Contact Us form and our team will get back to you.

Save Time and Stop Writing GraphQL Resolvers

Hasura — Wed, 01 Feb 2023 16:40:23 +0000

The conventional way of building a Data API through GraphQL involves building everything from scratch. That includes tasks such as:

writing boilerplate code for basic CRUD functionalities
implementing and maintaining GraphQL resolvers
optimizing the resolvers for performance
adding authentication and authorization
implementing data validation and error checking mechanisms

One of the most complex and time-consuming tasks is the implementation of GraphQL resolvers, though. Since the resolvers are the ones that generate a response for a GraphQL operation, it's critical to implement them properly.

However, as the complexity of the API increases, so does the effort and difficulty of coding the resolvers. Manually implementing the resolvers can be difficult for several reasons:

Boilerplate code: It requires a significant amount of boilerplate code for the CRUD operations
Complexity: The resolvers become complex once you add filtering, aggregations, authorization, and custom business logic
Performance: Inefficient implementation of resolvers can lead to an underperforming API
Maintenance: Maintaining the resolvers and keeping them up-to-date with changes in the schema and data sources is time-consuming

Moreover, you must ensure that the API is secure and can scale appropriately. All this work requires lots of effort and resources. What if you could eliminate all these challenges and time-consuming work? This article presents an alternative way of building GraphQL Data APIs without the difficulties of manually-built APIs.

Writing the GraphQL Resolvers manually

In this section, we'll go over a custom-built GraphQL API that represents a digital media store. The API is connected to the Chinook database, which includes tables for artists, albums, and tracks.

The figure below illustrates the GraphQL API.

Since the GraphQL resolvers are the main focus of this article, we'll only focus on them. We'll skip the other details that are not relevant to this article. However, you can see the complete application code on GitHub.

The schema of the GraphQL API looks as follows:

schema {
  query: Query
}

type Query {
  Album(id: Int!): Album
  Albums: [Album!]!
  Artist(id: Int!): Artist
  Artists: [Artist!]!
  Track(id: Int!): Track
  Tracks: [Track!]!
}

type Album {
  AlbumId: Int!
  Artist: Artist
  ArtistId: Int!
  Title: String!
  Tracks: [Track!]
}

type Artist {
  ArtistId: Int!
  Name: String
  Albums: [Album!]
}

type Track {
  Album: Album
  AlbumId: Int
  Bytes: Int
  Composer: String
  TrackId: Int!
  MediaTypeId: Int!
  Milliseconds: Int!
  Name: String!
}

Looking at the schema, you can see that the API only allows querying the database for artists, albums, and tracks. It doesn't enable mutating data, such as inserting, updating, and deleting records.

As a result, this GraphQL API has a couple of resolvers. A resolver for retrieving:

a specific album
all albums
a specific artist
all artists
a specific track
all tracks

The "resolvers" code looks as follows:

import { readFileSync } from "node:fs";
import { createServer } from "node:http";
import { createSchema, createYoga } from "graphql-yoga";
import { GraphQLError } from "graphql";
import DataLoader from "dataloader";
import { useDataLoader } from "@envelop/dataloader";
import type { Album, Artist, Resolvers, Track } from "./generated/graphql";
import sql from "./db";
import { genericBatchFunction } from "./dataloader";
import { keyByArray } from "./utils";

const typeDefs = readFileSync("../schema.graphql", "utf8");

const resolvers: Resolvers = {
    Query: {
        Album: async (parent, args, context, info) => {
            return (context.getAlbumsById as DataLoader<string, Album>).load(args.id.toString());
        },
        Albums: async (parent, args, context, info) => {
            const albums = await (
                context.getAllAlbums as DataLoader<string, Album[]>
            ).load('1');
            for (const album of albums) {
                (context.getAlbumsById as DataLoader<string, Album>).prime(
                    album.AlbumId.toString(),
                    album
                );
            }
            const albumsByArtistId = keyByArray(albums, 'ArtistId');
            for (const [ArtistId, albums] of Object.entries(albumsByArtistId)) {
                (context.getAlbumsByArtistId as DataLoader<string, Album[]>).prime(
                    ArtistId,
                    albums
                );
            }
            return albums;
        },
        Artist: async (parent, args, context, info) => {
            return (context.getArtistsById as DataLoader<string, Artist>).load(
                args.id.toString()
            );
        },
        Artists: async (parent, args, context, info) => {
            const artists = await (
                context.getAllArtists as DataLoader<string, Artist[]>
            ).load('1');
            if (!artists) {
                throw new GraphQLError(`Albums not found.`);
            }
            for (const artist of artists) {
                (context.getArtistsById as DataLoader<string, Artist>).prime(
                    artist.ArtistId.toString(),
                    artist
                );
            }
            return artists;
        },
        Track: async (parent, args, context, info) => {
            return (context.getTracksById as DataLoader<string, Track>).load(args.id.toString());
        },
        Tracks: async (parent, args, context, info) => {
            const tracks = await (
                context.getAllTracks as DataLoader<string, Track[]>
            ).load('1');
            for (const track of tracks) {
                (context.getTracksById as DataLoader<string, Track>).prime(
                    track.TrackId.toString(),
                    track
                );
            }
            const tracksByAlbumId = keyByArray(tracks, 'AlbumId');
            for (const [AlbumId, tracks] of Object.entries(tracksByAlbumId)) {
                (context.getTracksByAlbumId as DataLoader<string, Track[]>).prime(
                    AlbumId,
                    tracks
                );
            }
            return tracks;
        },
    },
    Album: {
        async Artist(parent, args, context, info) {
            return (context.getArtistsById as DataLoader<string, Artist>).load(
                parent.ArtistId.toString()
            );
        },
        async Tracks(parent, args, context, info) {
            const tracks = await (context.getTracksByAlbumId as DataLoader<string, Track[]>).load(
                parent.AlbumId.toString()
            );
            for (const track of tracks) {
                (context.getTracksById as DataLoader<string, Track>).prime(
                    track.TrackId.toString(),
                    track
                );
            }
            return tracks
        },
    },
    Artist: {
        async Albums(parent, args, context, info) {
            const albums = await (context.getAlbumsByArtistId as DataLoader<string, Album[]>).load(
                parent.ArtistId.toString()
            );
            if (Array.isArray(albums)) {
                for (const album of albums) {
                    (context.getAlbumsById as DataLoader<string, Album>).prime(
                        album.AlbumId.toString(),
                        album
                    );
                }

            }
            return albums || [];
        },
    },
    Track: {
        async Album(parent, args, context, info) {
            return (context.getAlbumsById as DataLoader<string, Album>).load(
                parent.AlbumId!.toString()
            );
        },
    }
};

export const schema = createSchema({
    typeDefs,
    resolvers,
});

const server = createServer(
    createYoga({
        schema,
        plugins: [
            useDataLoader(
                "getAlbumsById",
                (context) =>
                    new DataLoader((keys: Readonly<string[]>) =>
                        genericBatchFunction(keys, { name: "Album", id: "AlbumId" })
                    )
            ),
            useDataLoader(
                "getAllAlbums",
                (context) =>
                    new DataLoader(async (keys: Readonly<string[]>) => {
                        const albums = await sql`SELECT * FROM ${sql("Album")}`;
                        return keys.map((key) => albums);
                    })
            ),
            useDataLoader(
                "getAlbumsByArtistId",
                (context) =>
                    new DataLoader((keys: Readonly<string[]>) =>
                        genericBatchFunction(keys, { name: "Album", id: "ArtistId" }, true)
                    )
            ),
            useDataLoader(
                "getArtistsById",
                (context) =>
                    new DataLoader((keys: Readonly<string[]>) =>
                        genericBatchFunction(keys, { name: "Artist", id: "ArtistId" })
                    )
            ),
            useDataLoader(
                "getAllArtists",
                (context) =>
                    new DataLoader(async (keys: Readonly<string[]>) => {
                        const artists = await sql`SELECT * FROM ${sql("Artist")}`;
                        return keys.map((key) => artists);
                    })
            ),
            useDataLoader(
                "getTracksById",
                (context) =>
                    new DataLoader((keys: Readonly<string[]>) =>
                        genericBatchFunction(keys, { name: "Track", id: "TrackId" })
                    )
            ),
            useDataLoader(
                "getTracksByAlbumId",
                (context) =>
                    new DataLoader((keys: Readonly<string[]>) =>
                        genericBatchFunction(keys, { name: "Track", id: "AlbumId" }, true)
                    )
            ),
            useDataLoader(
                "getAllTracks",
                (context) =>
                    new DataLoader(async (keys: Readonly<string[]>) => {
                        const tracks = await sql`SELECT * FROM ${sql("Track")}`;
                        return keys.map((key) => tracks);
                    })
            ),
        ],
    })
);

server.listen(4000, () => {
    console.info("Server is running on http://localhost:4000/graphql");
});

This GraphQL API has a single purpose - to read the data from the database. Although the API is quite simple, it requires a considerable amount of code. Now imagine a complex enterprise application and the amount of code you would have to write.

The amount of code you have to write is one of many concerns. There are other things you need to think about, such as:

the N+1 problem
extending security rules per field in the schema
adding gateway features (caching, rate limiting, etc.)

All of the above is difficult and time-consuming to implement. Hasura solves issues such as the N+1 problem and provides features such as caching, rate limiting, and authorization by default.

N+1 problem

GraphQL query execution usually involves executing a resolver for each field. Let's say you are fetching artists and their tracks. Each "artist" record in the database would invoke a function to fetch their N "tracks". As a result, the total round trips become N+1, which could become a huge performance bottleneck. The depth of the query makes the number of queries grow exponentially.

Hasura mitigates the N+1 problem because, at its core, the server is a compiler. That means it compiles all GraphQL queries to a single SQL query, thus reducing the number of hits to the database and improving the performance.

Security Rules

Most applications require an authentication system to answer questions such as "Does this (valid) user have permission to access this resource or perform this action?". It specifies what data a particular user can access and what action the user can perform. Implementing such a critical system is a challenging task.

Hasura allows you to define granular role-based access control rules for every field in your GraphQL schema. It's granular enough to control access to any row or column in your database.

With row-level access control, users can access tables without having access to all rows on that table. This is particularly useful for protecting sensitive personal data, which is part of the table. This way, you can allow all users to access a table but only a specific number of rows in that table.

Row Level Permissions

Column-level access control lets you restrict access to specific columns in the table. This is useful to hide data that are not relevant, sensitive, or used for internal purposes.

Column Level Permissions

Combining both these rules gives a flexible and powerful way to control data access to different stakeholders involved.

How does it work? Hasura uses the role/user information from the session variables and the actual request to validate the request against the rules defined by you. If the request/operation is allowed, it generates a SQL query, which includes the row/column-level constraints from the access control rules. It then sends it to the database to perform the required operation (fetch the necessary rows for queries, insert/edit rows for mutations, etc).

Read more about Authorization and Access Control in the documentation.

Adding gateway features

A production-ready API requires features such as caching, rate limiting, monitoring, and observability. When you build the API manually, you must consider and implement all these features.

There can be latency issues and slow response times for GraphQL queries because of the response size, the location of the server, and the number of concurrent requests. Hasura has metadata about the data models across data sources and the authorization rules at the application level. This enables Hasura to provide end-to-end application caching. Cached responses are stored for a period of time in an LRU (least recently used) cache and removed from the cache as needed based on usage.

Read more about caching in the documentation.

Save time and resources

For enterprise-level Data APIs, the above features are a must. The API must be secure and performant. That results in massive work to implement just the basic CRUD functionalities. Once you add authorization, caching, rate limiting, and other features, it requires even more effort and resources.

What if you could skip all these tedious and time-consuming tasks? In the next section, you'll see how you can have a production-ready GraphQL API within minutes without writing code, plus all the above features (and more).

Building GraphQL APIs without writing resolvers

Hasura is a GraphQL Engine that makes your data instantly accessible over a real-time GraphQL API. It connects to your data source and automatically generates the GraphQL schema, queries, mutations, subscriptions, CRUD operations, and authorization.

It doesn't require writing any code unless you want to add custom business logic. You get everything out of the box.

Let's continue by creating a Data API with Hasura to demonstrate the power of Hasura. There are two ways to use Hasura:

using Hasura Cloud, which is the easiest way to use and build Hasura applications
using Docker to self-host it

This article uses Hasura Cloud. Navigate to your Hasura Cloud dashboard and create a new project by clicking the "New Project" button.

In the next step, click the "Create Free Project" button, and you should have a Hasura project up and running within seconds. You should see the console after launching the project.

The next step involves connecting the Hasura app to your database. Navigate to the "DATA" tab, then to "Create New Database", and click the "Create Neon Database" button.

The database should be created & connected within seconds.

Now click the "Create Table" button to create a new table. For this example, create a users table with the following columns:

id of type UUID (Primary Key)
username of type Text
country of type Text

Select the id as the Primary Key and save the table.

If you navigate back to the "API" tab, you should see all the available GraphQL operations. You get all the operations needed to access and mutate data without writing code (or resolvers). On top of that, you also get real-time capabilities.

This simple example demonstrates how Hasura improves the process of building and shipping Data APIs to production. It unblocks and allows developers to move extremely fast since they automatically get all the critical features.

How does that work

A GraphQL Resolver is a function that specifies how to process a specific GraphQL operation and turn it into data. A conventional GraphQL API can't exist without resolvers because they are an essential part of it.

Hasura takes a different approach, though. Instead of using the conventional GraphQL resolvers, it uses a GraphQL Engine. The engine, which is actually a compiler, compiles the GraphQL operation into an efficient SQL query.

Let's take the Chinook database as an example again. The Chinook data model represents a digital media store, including tables for artists, albums, media tracks, invoices, and customers. The example below illustrates a couple of untracked tables.

When the tables are untracked, they are not exposed over the GraphQL API. To expose them to the public, you need to track them. When you track the tables, the GraphQL Engine automatically generates a bunch of things, such as:

a GraphQL type definition
queries
mutations
subscriptions

Check the docs for the complete list of things it generates.

Once the engine tracks the tables, it knows how to respond when users request data from the database to which these tables belong. You can also see the available operations in the "Explorer" tab.

As mentioned earlier, Hasura compiles the GraphQL operation into a SQL query. Consider the following query from the above image:

query {
  Album {
    Title
  }
}

Click on the Analyze button to see what happens under the hood when you run the query. Clicking the button opens a new pop-up with the "Generated SQL" and the "Execution Plan", as shown in the image below.

The generated SQL statement for the query is as follows:

SELECT
  coalesce(json_agg("root"), '[]') AS "root"
FROM
  (
    SELECT
      row_to_json(
        (
          SELECT
            "_e"
          FROM
            (
              SELECT
                "_root.base"."Title" AS "Title"
            ) AS "_e"
        )
      ) AS "root"
    FROM
      (
        SELECT
          *
        FROM
          "public"."Album"
        WHERE
          ('true')
      ) AS "_root.base"
  ) AS "_root"

That's how Hasura works. Instead of using GraphQL resolvers, it generates SQL statements at runtime and then runs them against your database.

The video illustrates how Hasura doesn't need to use resolvers for data interop and what the key differences are with other systems.

Additional resources to learn more:

Adding custom business logic

Even though Hasura doesn't use resolvers, you can join your existing GraphQL APIs with your Hasura application. That's possible with the help of Remote Schemas.

Remote Schemas

Hasura can merge remote GraphQL schemas and provide a unified GraphQL API. Think of it like automated schema stitching. All you need to do is build your GraphQL service and provide the HTTP endpoint to Hasura. Your GraphQL service can be written in any language or framework.

That enables users to connect their existing GraphQL API to their Hasura application. For instance, if you have a GraphQL payment API, you can join it to your Hasura application with the help of Remote Schemas.

Read more about Remote Schemas in the documentation.

Additionally, there are other ways of adding custom business logic, such as Actions and Event Triggers.

Hasura Actions

Actions are a way to extend Hasura's schema with custom business logic using custom queries and mutations. Actions can be added to Hasura to handle various use cases such as data validation, data enrichment from external sources, and any other complex business logic.

Additionally, Actions in Hasura allow for integrating new and existing REST APIs with your Hasura application. For example, if you have a Node.js REST API for sending emails, you can plug it into Hasura without making any changes to the existing API.

Read more about Actions in the documentation.

Event Triggers

Hasura can be used to create Event Triggers on tables in the database. Event Triggers reliably capture events (such as insert, update, and delete) on specified tables and invoke HTTP webhooks to carry out any custom logic.

A simple example would be triggering an API endpoint to send a welcome email once a user is added to the database.

Read more about Event Triggers in the documentation.

Summary

Exposing your data via a GraphQL API doesn't mean you need to spend resources and effort building it manually. You can let Hasura do all the heavy lifting for you. In the use cases where you require custom business logic, you can add it with the help of Actions, Remote Schemas, and Event Triggers.

Additional material:

Announcing Pod42, the Hasura ChatGPT Bot

Hasura — Wed, 25 Jan 2023 13:30:38 +0000

We are happy to announce the launch of Pod42, a bot that answers questions related to Hasura. It uses the GPT AI model, trained on resources like Hasura’s docs, learn and blog portals.

Note: It’s in alpha, so expect some bugs or issues with answers and the sources it gives.

Getting started with Pod42

The bot has been integrated into our discord server. In case you haven’t joined yet, head over to https://hasura.io/discord to join HasuraHQ discord server.

Once inside the server, head to #pod42-support channel and tag the @Pod42 bot to ask a question. The format for asking a question looks something like:

@Pod42 <question>

// example
@Pod42 What is Hasura?

Testing for fun

Here are some of the answers we have been getting from the bot after training it with our data sources.

Why use Hasura?

A fun attempt by David below:

Another one about read replicas:

Disclaimer

The bot is in alpha, which means it might give inaccurate or incomplete answers sometimes. Use the source/s to verify the information, and when in doubt, reach out to help-forum. Also, we're constantly training Pod42 to improve it. If you have any feedback, please let us know. Any feedback is appreciated!

GraphQL Security in Production with Automated Allow Lists

Hasura — Thu, 19 Jan 2023 10:32:09 +0000

In some cases, you might want to restrict your Hasura application to a limited number of GraphQL operations (queries/mutations/subscriptions). The reason for doing it might be to avoid excessive data exposure, API scraping and to protect your application & data.

Hasura allows you to restrict the number and type of available operations with the "Allow List" feature. The "Allow List" represents a list of allowed GraphQL Operations that can be executed in your application. So the Hasura GraphQL Engine only runs the operations specified in the "Allow List".

Moreover, there is a way to generate an Allow List based on your front-end code automatically. This way, the allow list and your front-end code are always in sync!

The article presents 3 ways to generate allow lists in Hasura, with the last one being fully automated.

Enable "Allow List"

The "Allow List" feature is disabled by default. You need to navigate to your project settings and enable it.

Set the HASURA_GRAPHQL_ENABLE_ALLOWLIST environment variable to true, as shown in the figure.

Allow List of operations in Hasura

Let's use the following Hasura application as an example. It's a simple application that stores users. Each user has an id and a name.

Navigate to the API tab and click on the Allow List at the top of the page (right-hand side).

That opens the "Allow List" manager. This is where you can add, modify and remove operations in your "Allow List".

Clicking on the Add Operation button opens a new modal where you can add an allowed operation. There are 3 ways to add an operation:

write it manually
upload a file with the operation/operations
pick it from the Quick Add dropdown (it displays the latest operation executed)

After you add the operation, you can see it on the "Allow List" page.

Another way to create an AllowList

There's another way you can manage your "Allow List". Navigate to the MONITORING tab and click on the Allow Lists option.

If you navigate to the NEW OPERATIONS page, you can see the operations you executed that are not in the "Allow List" yet. That means Hasura Cloud allows you to choose from a list of operations you executed previously and add the ones you want to the "Allow List".

Instead of manually writing the operations, you can select the ones you want to add to the "Allow List" and click the Add to Allowlist button.

After that, you should see them on the ALLOWED OPERATIONS page.

Automatically Generate an AllowList

Creating an AllowList manually is fine, especially when the application is not large. However, once the application grows, it can become time-consuming to manually add operations to the AllowList. Keeping the list in sync with your front-end code can also be tedious.

Thankfully, there is a way to automate that with the GraphQL Code Generator library. The GraphQL Code Generator automatically generates code from your GraphQL schema and operations. It also has a plugin @graphql-codegen/hasura-allow-list that automates the creation of the "AllowList" based on the GraphQL Queries found in your front-end code.

After you set up @graphql-codegen in your project, add the following to your codegen file:

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
 generates: {
  'path/to/metadata/allow_list.yaml': {
    plugins: ['hasura-allow-list']
  }
 }
}

export default config;

Now that the process of creating the "AllowList" is fully automated, the "AllowList" and your front-end code are always in sync.

Note: The plugin only works in the JavaScript ecosystem.

It's important to mention that this is a community plugin, and not the official Hasura solution.

Additional resources:

The rise of GraphQL APIs on data warehouses

Hasura — Tue, 17 Jan 2023 12:16:47 +0000

TL;DR

Data warehouses are used to store valuable enterprise data. Data APIs – both GraphQL and REST – are emerging as a tool to power frictionless and high-quality integrations between applications/services and data in enterprise data warehouses. In this article, we will talk about drivers behind the rise of data APIs on data warehouses, challenges with current approaches to building, operating, and scaling data APIs, and how Hasura is addressing those challenges for our customers.

The rise of data warehouse integrations
Top use cases for data warehouse integration
Data APIs are the solution to data warehouse integration
Building APIs the traditional way can be slow and expensive
Building and scaling GraphQL and REST APIs faster with Hasura
Get started with instant API on your data warehouse

The rise of data warehouse integrations

Cloud data warehouses such as Snowflake, Google BigQuery, Amazon Redshift, etc. have seen a dramatic increase in adoption over the past few years. The maturity of the solutions themselves and the tooling (ETL) around them has improved a lot as well, making their adoption and usage a lot more tractable.

With the broader movement to become more data-driven as well as to get more from their data investments, enterprises are constantly looking for ways to bring data into more initiatives, decisions, and experiences. How can the data be shared more widely (but in a secure and compliant way) to enable more internal and external stakeholders to make better decisions? How can data be incorporated into applications to build more delightful user experiences – for customers, partners, and employees.

Top use cases for data warehouse integration

Let's take a look at the top 3 data-first use cases

Data-as-a-product to other teams in the org

Teams that own data want to publish it to other teams in their organization or externally to other partners. Increasingly they want to think of their data as a product.

Example: Buyers with very high returns because of fraudulent reasons

Embedded data features in existing products (apps or services)

End users of digital products are increasingly expecting their product experience to be "smarter". For offline products, users benefit from a digital management and analytics experience. At the same time, product and business teams know that intelligent features can drive increased stickiness, retention and usage of their products.

Example: Show "predicted" end of month bills on a consumption-based billing service. Or, surface a customer 360 type of view for internal marketing and sales teams by aggregating data across multiple tables and data sources.

Integrations to enrich data in other business tools

Enterprise tools and SaaS products (like Marketo, Salesforce, etc.) that are the operational foundation for the business can become a lot more valuable when they are integrated with more data and context, which usually resides in a data warehouse.

Example: Visualising data using Google's data studio.

Data warehouses themselves are evolving to keep up with the demand for extracting more value from data. For example, Google Cloud has been investing heavily in BigQuery ML that allows teams to leverage their existing SQL knowledge to easily create and use ML models.

The desire for integrating transactional and analytical use-cases has led to Snowflake announcing Snowflake Unistore – their unified platform that brings product use-cases to the core CDW value-proposition that they are known for. However, customers are still looking for better ways to integrate their warehouse data into these use cases.

Many are coming to the conclusion that APIs (and more specifically GraphQL APIs) are the most flexible, secure, and performant way to enable these use cases on their data warehouses.

Let’s look at why data APIs are well-positioned to address these use cases.

GraphQL Data APIs are the solution to data warehouse integration

Before we dive into why APIs are the best way to power this new breed of integration needs, let's look at how organizations primarily access data in their warehouses today, and why/how those current approaches fall short for these newer use cases.

The 2 primary ways of connecting to data warehouses is either via JDBC / ODBC connectors in 3rd party applications or by writing SQL (or derivative) queries directly against the data. Both of these approaches are great for traditional analytics and visualization needs. For example visualizing data in a BI or visualization tools like Tableau or Looker; or querying and analyzing data for analytics and reporting use cases.

But this type of direct access to data doesn’t work for these new integration use cases because it tightly couples the consumption layer with the data layer in a way that is hard to maintain, operate, and secure. A data API access layer becomes necessary. Let’s look a few scenarios

Multiple applications/services need access to the same data

Multiple tenants connected to the same database makes it hard to evolve the data and schema of the database, or to provide performance QoS or tiers to different consumers. Building an API layer between the producer and consumer allows decoupling, and provides an intermediate layer that can absorb those changes in a more elegant way.

Enforcing authentication & authorization without an API is painful

IAM in data warehouses are geared towards providing secure access to individuals and analysts, but are not ideal for application/service integrations.Sharing database credentials with multiple applications becomes a management headache and a potential security nightmare. Applications probably have a centralized authentication mechanism that should be leveraged, but databases typically don't integrate with that directly.

Furthermore, entitlements (especially fine-grained policies) that govern access to certain rows or columns of data based on properties of the end-user or the application are hard to manage and enforce in the data warehouses because they don't provide those capabilities or because maintaining those policies in the data warehouse’s proprietary setup makes it hard to scale reviewing & auditing these security policies.

GraphQL APIs allow data consumers to fetch just the data they need

Direct access is fine when the consumer is trying to pull data that lives in a single table / view. But, can be inefficient because of multiple request roundtrips if you need to pull and join data from multiple tables/views/databases, etc. This inefficiency can have a non-trivial cost and performance impact depending on level of overfetching and query volume. REST APIs can also suffer from this limitation. GraphQL was created to solve exactly this problem for transactional workloads, and is gaining popularity for addressing this issue for analytical / OLAP data sources as well.

All these reasons make APIs, and more specifically GraphQL APIs, a more elegant way to address the data integration use cases for data warehouses.

Building APIs the traditional way can be slow and expensive

While GraphQL/REST APIs are great fit for these data integration use cases, building, scaling, and operating APIs can be a time-consuming task, which can in turn cause organizations to shy away from API-driven approach to data warehouse integrations.

Here are just a few of the many things that add time and effort to build and operate APIs.

Creating a single API end point requires developer to build and maintain these:

Boilerplate code for CRUD API
Mapping client types and schema
Baking authentication and authorization is tedious and risky
Validation and error checking code in the API layer

Building GraphQL API brings additional costs. Developers need to write and maintain resolvers to map the GraphQL query to the underlying SQL queries. The effort to write resolvers increases significantly with the richness and complexity of the GraphQL queries, for e.g. if you have filtering, aggregations, complex and/or logic, etc. Furthermore, making sure that the resolvers are written in a way that the resulting GraphQL query is performant takes more planning and optimization.

Operating APIs efficiently brings its own set of challenges. Making sure that the APIs are performant, reliable, and can scale smoothly with load can become a heavy lift, especially as this expertise is not typical in teams managing the central data warehouse. Updating the API to keep up with changes at the database level needs some discipline as well to make sure the consumers have a smooth experience.

Hasura completely eliminates these challenges with traditional API creation and operation workflows. It allows organizations to become API-driven, but without all the effort that goes into API creation, scaling, security, and operations.

Building and scaling GraphQL and REST APIs faster with Hasura

Hasura provides a GraphQL API over transactional sources of data, and over the last year we've been seeing first-hand how developers and teams increasingly need to access data from a data warehouse.

Hasura allows rapid creation of GraphQL APIs (or REST) by just configuring the data sources and the mapping of underlying data models into API models, and then Hasura provides an API that has joining, filtering, pagination & aggregation capabilities built-in. Hasura also has a session-aware caching layer that makes integrations with realtime applications easier with OLAP and CDW systems.

Imagine the following the eCommerce schema in a Data Warehouse

An API call that fetches users based on number of orders they've made, is a normal query to make, but is challenging to represent as a flexible REST API call:

An API call that fetches orders based on what region the users are in, without fetching unnecessary user data:

Streaming Subscriptions

If you have a large amount of data, or "fast moving" data in Postgres, Hasura now allows you to instantly create an API for clients to fetch that data as a continuous stream. This API can be safely exposed to internal or external HTTP clients.

For example, in the users placing orders scenario, during holiday season, there would be plenty of orders coming in every second. We can make use of streaming subscriptions to async load the data on the UI and not bombard the client to fetch orders which are still pending payments.

subscription getPendingOrders {
  orders_stream(cursor: {initial_value: {created_at: "2023-01-01"}, ordering: ASC}, batch_size: 2) {
    id
    amount
    created_at
    user_id
  }
}

GraphQL Streaming Subscription with Hasura

Performance

Hasura is highly optimized for performance, scalability and reliability. Hasura also provides caching and query optimization services, which further help improve performance.

Caching

Now, some queries are more frequently accessed than others. Typically, there could be latency and slow response times due to the size of the response, location of the server (in a distributed multi-region app), number of concurrent API calls.

Hasura has metadata about the data models across data sources, and the authorization rules at the application level. This helps Hasura to provide end to end application caching.

High performance GraphQL to SQL Engine

Internally Hasura parses a GraphQL query, gets an internal representation of the GraphQL AST. This is then converted to a SQL AST and with necessary transformations and variables the final SQL is formed.

GraphQL Parser -> GraphQL AST -> SQL AST -> SQL

This compiler based approach allows Hasura to form a single SQL query for a GraphQL query of any depth.

GraphQL helps make one API call to fetch related data and a precise subset of data, instead of making multiple REST API calls that might return potentially redundant data.

This has a cost implication because only the right subset of data is fetched and a single query is executed to fetch related pieces of data (as opposed to multiple REST API calls that fetch more data than is necessary)

Security

Hasura has a fine-grained authorization engine that allows creating policies to restrict access to only particular elements of the data based on the session information in an API call.

Hasura Authorization and Authentication

Row level and column level permissions

Hasura supports role-based access control system. Access control rules can be applied to all the CRUD operations (Create, Read, Update and Delete). Some operations can be completely restricted to not allow the user perform the operation.

Row Level Permissions

Column Level Permissions

The rules can be setup easily using Hasura Console, where you define a role and setup rules for access.

For example, for row level permissions, we can set up filters like

{"user_id": {"_eq": "X-Hasura-User-Id"}}

The above rule is equivalent to saying: allow this request to execute on the current row if the value of the user_id column equals the value of the session variable X-Hasura-User-Id.

Column Level Access Rules

Get started with instant API on your data warehouse

Hasura supports BigQuery, Snowflake, Amazon Athena, and Postgres flavors like AlloyDB and Hydra (geared for OLAP). If you and your team are looking at exposing data warehouse data over an API, Hasura can significantly reduce the time and effort to do so, in turn freeing up your developers to do other high-value work with direct ties to business outcomes.

To get started follow our guides to get instant APIs on Snowflake or BigQuery.

You can see other guides here.

Or, reach out to the Hasura team for a custom demo to get all your questions answered about how Hasura can accelerate your path to APIs on data warehouses.

Best Practices Guide for GraphQL Observability with Hasura [Part 1]

Hasura — Fri, 06 Jan 2023 11:16:00 +0000

Hasura is an open-source product that accelerates API development by 10x by instantly giving you GraphQL or REST APIs on your data. Hasura plays a central role in your application stack as it can call out to your other services and databases while adding authorization and caching on top. Your development teams can quickly access critical data that powers their applications. Please see our website for more information.

Note: This is a multi-part series. The current post delves into the various Observability metrics relevant for apps built with GraphQL / REST APIs. In the next parts, we will talk about the use cases and how Hasura specifically solves them.

Observability

As your app grows and becomes more complex, it becomes increasingly difficult to understand how it is used and performs. This is where observability comes in. Observability is the ability to gauge a system’s internal conditions by looking at its outputs, such as metrics or logs. Observability means you can:

Gain insights into the functionality and health of your systems, collect data, visualize them, and set up alerts for potential problems.
Have distributed tracing provide end-to-end visibility into actual requests and code, helping you improve your application’s performance.
Audit, debug, and analyze logs from all your services, apps, and platforms at scale.

Because Hasura can act as a central gateway for your application stack, we take observability very seriously.

SLOs, SLIs, and the Three Pillars

The path to thoroughly observing any app is to ensure you have your SLOs defined, SLIs identified, and telemetry data that enable the collection of those SLIs. In production, your SRE team would define service level objectives (SLO) that are intended to measure the reliability of your app. Each SLO is a target value or range of values for a service level measured by a service level indicator (SLI). For example, a service level indicator could be the number of requests per second, and an SLO could be that our app needs to be able to serve a minimum of ten thousand requests per second.

Once our SLOs and SLIs are defined, we use the three pillars of observability to ensure we are meeting our objectives.

The Three Pillars of Observability

Observability relies on three key pillars: logs, metrics, and traces. Access to these components does not automatically make systems more visible, but when used together, they can provide powerful tools for understanding a system’s internal state.

Metrics are used to determine if there’s a problem to begin with. They provide snapshots of a system’s metadata, such as server resources used or requests per second. Metrics can monitor performance, identify trends, and set alerts for potential troubles.
Traces, used to find where the problem is, provide end-to-end visibility into a system’s operations by tracing requests through all the different services. Traces can show how a system is functioning, identify bottlenecks, and improve performance.
Logs, used to determine what the problem is, provide timestamped messages of events in a system. You can use them to debug issues.

Hasura Cloud and Enterprise come out of the box with logs, tracing, and the following metrics:

Request rate
Error rate
Average request execution time
Active subscriptions
Number of WebSockets open

All observability data is available via the Hasura Console, one of our APM integrations such as Datadog and New Relic, or any APM receiver that supports the OpenTelemetry specification.

With the traditional way of rolling your own GraphQL server, you have to manually set up all your resolver logic, observability, and authorization code.

Hasura Cloud and Enterprise come with support out of the box.

Metrics

Request Rate

The request rate represents how many requests a service receives per unit of time, such as 100 requests per minute (RPM). This is the most fundamental metric, as you must design your entire architecture around your expected request rate. As this metric grows, you must scale up your system with techniques such as database sharding or risk your system being overwhelmed and unreliable.

How to Use

Request rate tracks the overall usage of a system. It becomes too performance-intensive at high request rates to monitor every request. Instead, you would sample a percentage. Some other best practices:

Scale our services up and down dynamically based on the request rate. An example is Hasura Cloud’s automatic horizontal scaling.

If there are trends in RPM, such as more requests in the morning, you can pre-provision infrastructure.

When RPM spikes above expected usage, an alert should warn of a possible DOS attack.

High RPM from specific users may warrant setting up IP or auth-based rate limiting.

Error Rate

The error rate represents how many errors a service receives in a period of time. Most HTTP APIs signal errors via HTTP status codes, 400 for client errors and 500 for server errors. GraphQL differs because most errors are in the body’s errors key. Hasura automatically parses both forms of errors for you.

Errors are an inherent part of distributed systems. Network communication is complex, and a lot can go wrong.

How to Use

Error rates are a good indicator of the overall health of your systems and are often the quickest way to spot problems. We can distinguish apparent disruptions over background noise by viewing the error rate over time and looking for patterns.

A couple of ways you can use the error rate are monitoring to quickly roll back deployments when deploying service updates using techniques like canary or blue-green deployments or triggering an alert anytime the error rate is over a baseline amount.

Viewing Individual Errors

For REST HTTP APIs, the HTTP status code tells us general information about the error. For example, HTTP 429 “indicates the user has sent too many requests in a given amount of time”. Based on the code, we can begin troubleshooting.

GraphQL does not use HTTP status codes unless it’s a server error. Instead, the response object has an errors key that you need to check for errors.

Average Request Execution Time

The average request execution time is calculated by the total time taken by all requests during time range / time range in minutes.

How to Use

Latency is a huge factor in user experience, so as developers, we should try as hard as possible to reduce this metric. If your data allows it, caching built into Hasura is a significant first step in lowering execution time. Using tracing, which we learn about in an upcoming section, we can see remote APIs that need to be optimized or queries for which we may need to add an index.

Subscriptions

With Hasura GraphQL subscriptions, there are two main components: database subscriptions and the WebSocket connection to the client.

How to Use

Primarily useful to monitor performance, the subscription metrics allow you to see the usage of GraphQL subscriptions. You can see a list of clients connected via WebSocket. The database subscriptions feature helps you diagnose any database performance issue related to subscriptions. To understand the mapping between a WebSocket client and the underlying database subscription, please check out this article on how we scaled to one million GraphQL subscriptions.

Logs

Once metrics have identified an incident, you can drill into individual logs to find the root cause. Hasura has many logging options, such as choosing what layers emit logs, so please read the documentation. Here are a few ways we can use the Hasura logs to monitor our system:

Aggregating by Query Name

With typical REST HTTP APIs, we aggregate our statistics by the endpoint. Since GraphQL uses one endpoint for all requests, we should combine the security feature of allow lists with aggregating by operation name. This reduces our monitoring surface drastically because all queries are determined ahead of time.

This view is built-in to Hasura Console but can be done with any APM system using the data in the query-log layer.

Diagnosing Errors

Requests to Hasura record success or error in the http-log layer. Once your metrics alert on an abnormal error rate, search your logs for the level: error. The response objects have an error key with the GraphQL error.

Distributed Tracing

A request can go through many services; therefore, it can be difficult to see where it failed or slowed down. Distributed tracing via the B3 spec combined with observability tooling allows you to follow a request through its life and pinpoint issues.

Hasura, acting as the API gateway, can trace external APIs and database queries.

External API Tracing

When a request comes into Hasura, it generates a B3 header if one doesn’t already exist. Whenever an API encounters a B3 header, it will report its request metrics to an APM system. The APM system then aggregates all the information to build a trace for each request, allowing you to visualize them efficiently.

Database Tracing

There is no standard method for trace propagation in Postgres, so Hasura injects a transaction-local JSON variable.

To get the trace information into database logs and native database monitoring tools, query tags are used. Query tags are SQL comments appended to the generated SQL statements with tracing metadata. Tools like pganalyze can use them to help you optimize your queries.

Quickly and easily set up a GraphQL API and explore Hasura’s observability features for free on Hasura Cloud.

Summary

In conclusion, observability is a critical aspect of modern systems. By collecting and analyzing data from logs, metrics, and traces, you can gain valuable insights into the health and performance of your services. With the right tools and techniques offered out of the box with Hasura Cloud and Enterprise, you can improve the observability of your systems and ensure that they are functioning optimally.

Top 3 Reasons why Enterprises Choose Hasura

Hasura — Tue, 20 Dec 2022 09:46:42 +0000

GraphQL is a popular choice for enterprises looking to improve the performance, efficiency, and flexibility of their APIs. Functionality like being able to fetch very specific data (no over or under-fetching), having a strongly typed system, and schema introspection all make GraphQL a great choice.

However, building a GraphQL API manually requires considerable time, effort, and investment. Engineering organizations need to write a significant amount of code by hand just for the basic CRUD functionalities of your GraphQL API. Adding authorization, multiple data sources to your end-point, and custom business logic requires even more work and code. This work will likely take months or even years depending on complexity and a team of developers.

We find more and more enterprises asking themselves whether their business is a GraphQL business or not. Why spend time and resources on tedious tasks that are not actually core to your IP when you can get the most heavily leveraged GraphQL functionality out of the box?

This is where Hasura comes in.

Hasura is an open-source product that auto-generates GraphQL or REST APIs with a built-in authorization layer for your data. Point Hasura to the databases, REST & GraphQL endpoints, and third-party APIs, and it provides a unified, connected, real-time, and secured GraphQL API for all of your data.

Hasura speeds up the development process, and in this article, we will explore the top three reasons why enterprises choose Hasura for their GraphQL needs.

Data Access

Data in the modern world most likely comes from multiple sources. In an enterprise environment, you might have data from sources such as your database(s), internal APIs, and third-party services.

That means there are time-consuming and repetitive tasks, such as connecting those data sources to your applications. After you connect them, the work continues by ensuring they function properly on their own and with the other existing data sources.

So each time a new data source needs to be integrated with an existing application, the process repeats:

Integrate the data source -> configure it -> test it -> maintain it

That can quickly become a bottleneck that slows down the development team and the application. So the question is - is there a better alternative? The alternative is Hasura.

As the diagram shows, Hasura abstracts all the tedious, boring, and time-consuming work. You connect all the data sources (databases, REST and GraphQL APIs) to Hasura, and it automatically generates a unified, secure, and real-time GraphQL API.

In the case of databases, the Hasura GraphQL Engine automatically generates the GraphQL Schema and operations such as queries, subscriptions, and mutations. It also enables you to connect existing REST and GraphQL APIs to your Hasura application.

Hasura unifies all data sources and enables the client to access unified data through the GraphQL API provided by Hasura. Creating a unified data-access API layer also allows developers to access and manipulate data in their database without having to write complex SQL queries. To access the data, developers can use the GraphQL API endpoint provided by Hasura to send queries and mutations that specify the data that should be retrieved or updated.

Hasura provides several tools and features to help developers work with data more effectively. For example, the Hasura Console provides an intuitive interface for exploring and testing the GraphQL API, and the Hasura CLI allows developers to manage their data from the command line.

Overall, Hasura’s approach to data access makes it easy for developers to work with their data and build robust and scalable applications on top of enterprise data.

API Production Readiness

In addition to improving data access, another primary business value Hasura provides is reducing the time to market by offering you critical features out of the box such as:

caching
real-time capabilities
authorization
observability

... and much more.

As mentioned previously, building a GraphQL API manually requires effort just for the basic functionalities. Implementing complex operational features like caching, real-time capabilities, or authorization requires even more effort.

Traditionally, building an API manually takes weeks or months and a team of developers. In this process, the developers also need to optimize the API to be production ready. That includes security, authorization, availability, scalability, and observability.

Hasura transforms the process of building the API into a service that comes with features such as authorization, real-time capabilities, observability, and availability out of the box. And everything highlighted in the above diagram.

Hasura and the developer tooling around it are designed to help teams build products faster and more efficiently.

Increased Developer Productivity

Hasura cuts down development time by 50% to 80%. You can find more from our case studies here. Hasura does this by automating key GraphQL development tasks such as defining schemas, writing resolvers, and setting up a server. Secondly, it automates and abstracts tedious tasks such as:

defining the GraphQL schema
defining and implementing the GraphQL resolvers
creating and configuring the GraphQL server

... plus other mundane work.

Such features are critical for an enterprise and tricky to implement. They require experienced API developers and a considerable amount of effort and time. Once they are implemented, someone needs to maintain them. Letting Hasura take care of them improves the developers’ productivity as they can focus on other critical tasks, like delivering core IP back to the business.

Another thing that increases developer productivity is Hasura’s metadata. The metadata is the brain of a Hasura application that captures vital information such as the following:

connections to the data sources
mapping the model from the data sources into an API
relationships between the models
authorization rules

Hasura uses this metadata information to generate a JSON API schema and exposes it through a GraphQL API. GraphQL is ideal for working with JSON data, as it is native to the JSON format. As an API specification, GraphQL allows developers to create flexible and powerful APIs that can operate on a wide range of data models and support a variety of methods. At the same time, it maintains the controlled boundaries that are necessary for a web service.

Developers can then use the metadata to configure and manage their applications. As a result, it improves the developer experience and productivity since developers don’t have to write code to configure or enhance their applications.

Summary

Most of the work involved in building a Data API via GraphQL is either tedious and repetitive or difficult and time-consuming. It’ll require lots of effort and resources.

But it doesn’t have to be that way. Hasura enables enterprises to build a production-ready Data API, with all the critical features, without having to write any code. That makes it easy for developers to quickly and easily build scalable and reliable applications without spending time on tedious and complex tasks.

Overall, Hasura offers a comprehensive and robust platform for enterprise application development.

Introducing Instant GraphQL APIs for Snowflake Cloud Data Platform

Hasura — Tue, 06 Dec 2022 18:14:33 +0000

Real-time access to data is essential for building modern applications. However, as the data footprint in an organization grows and spreads, it creates unique challenges for developers who need to aggregate data across multiple sources and develop the necessary APIs to securely and efficiently access and serve the data required to power their applications.

To help development teams with these challenges, we're excited to announce the beta release of our new GraphQL Data Connector for Snowflake. This powerful new database integration will allow Hasura users to instantly create a unified GraphQL API that runs read-only queries across all your Snowflake data. Hasura drastically reduces the time and effort required to build and secure data APIs, allowing teams to quickly power their analytical applications with data aggregated in Snowflake.

Important - This beta release of the Hasura GraphQL Data Connector for Snowflake supports read-only queries. During the beta period, the connector is available for Hasura Enterprise Edition (EE) and all Hasura Cloud customers. Once this integration moves to General Availability (GA), it will only be available in the Hasura Enterprise plans. For more information, read our docs.

What is Snowflake?

Snowflake, often referred to as a Cloud Data Platform, provides a way to bring together and easily access data siloed across multiple sources. Snowflake enables elaborate application development, collaboration, and more across a wide spectrum of data sets, all in the cloud. This provides massive horizontal scalability along with other capabilities that meet a wide variety of application, reporting, and other data consumption needs.

Building Applications with Snowflake and Hasura

Hasura customers across many industries, such as construction, energy, financial services, healthcare, and human resources, use Snowflake to house critical data needed to derive insights and make data-driven business decisions. Many of these customers also use or want to use Snowflake data to directly power analytics in internal and external data applications. Or they want to open their Snowflake data – in a safe and controlled way – to internal or external stakeholders to make data-driven decisions. However, this journey has some challenges.

The resource-intensive nature of building an API, especially if they intend to build multiple apps and services that use data from Snowflake.
Customers have to maintain and manage secure connections to Snowflake so only the authorized individuals and applications have access to this business critical data.

To address these challenges, our new integration with Snowflake helps by:

Providing an instant GraphQL API on Snowflake to access data securely.
Providing a unified GraphQL endpoint across Snowflake and other data sources such as PostgreSQL, SQL Server, BigQuery, Amazon Athena and CockroachDB. GraphQL is an extremely flexible query language for APIs and a runtime for fulfilling those queries with your existing data.
Bringing Hasura's out-of-the-box capabilities to Snowflake, such as:

a. Query response caching allows you to cache responses in Hasura for frequently executed queries as opposed to retrieving the data from Snowflake every time. This greatly improves application performance and consequently your end-user experience.
b. Declarative authentication and authorization
c. API security
d. Integration with your custom REST API application workflows via Actions and Event Triggers
e. Observability to ensure the reliability of your application stack

The new data connector for Snowflake introduces new ways to query, correlate and aggregate data, enabling Snowflake customers to do more with their data and increase the ROI on their Snowflake investments across the board.

What Can I Build with Hasura and Snowflake?

We’ve seen some really creative use cases that are only possible by integrating Hasura with our new Snowflake database connector. Below are a few examples to explore with your team.

Surface Analytics Data in Customer-facing and Internal Apps

Embedding analytics directly into applications is not only creating great user experiences, but it’s also helping teams build a competitive advantage. Quick and efficient data access is essential for building applications like an internal customer service dashboard that surfaces real-time analytics and helps deliver world-class customer support. With Hasura GraphQL, development teams can quickly build a unified API for Snowflake that efficiently serves up data from multiple tables, all within a single query, instead of making multiple fetches to individual tables. This saves developers countless hours of writing additional APIs and queries required to surface data from Snowflake.

Share Snowflake Data with Internal and External Consumers via APIs

In an effort to be more data-driven, organizations want to open their Snowflake data to more internal and external stakeholders, giving them the data they need to make better decisions. But given the critical and sensitive nature of the data often stored in Snowflake, organizations are often hesitant to do this through typical built-in connectors (eg. JDBC) and prefer to share just the data they want via APIs. API services allow them to provide data access in a secure, controlled, and limited way. With the Hasura connector for Snowflake, customers can now generate those APIs in a fraction of the time it would have otherwise taken to build. With the built-in Hasura authorization engine, customers are also able to easily implement access privileges into the API layer.

Joining Data from Snowflake and Other Sources

While Snowflake is often used as a central data warehouse, large organizations can still have critical data stored in other locations for a variety of reasons. Architecture or security designs, legacy databases that have yet to be migrated, or siloed business units can all lead to data being stored in locations outside of Snowflake. This poses a challenge when building applications that require data across those multiple sources. Hasura GraphQL creates an easy and efficient way to join Snowflake data with data from those additional sources. For example, maybe a company needs to map order data and shipment data during order fulfillment. Joining these tables across multiple data sources helps drive better product insights for things like returns, quality issues, and buyer profiling.

What’s Included in the Snowflake Connector Beta?

The Hasura connector for Snowflake currently provides query support only, along with a host of other standard Hasura features called out above. For example, connecting two tables is a standard Hasura feature that really stands out when working with denormalized reporting data that is often used in Snowflake. For a full list of capabilities, visit the documentation.

How Can I Get Started?

To get started, you will need

An existing Snowflake account instance and data to connect Hasura to query against.
A Hasura Cloud or Hasura Enterprise Edition self-hosted setup - version 2.16.0 or later.

While the Snowflake connector is in beta, it is behind a feature flag. Please follow the steps outlined in the documentation to learn how to enable it.

Navigate to the Data tab as shown and click on Connect Database. The following dialog requires four steps:

Turn on the experimental features.
Select Snowflake (beta) from the dropdown. This will then shape the rest of the connection form elements for the appropriate data needed for the Snowflake connection.
Set the name you’d like the connection to be listed as.
Add the JDBC connection string to your Snowflake instance. The JDBC connection string will need the URI path with credentials, warehouse, database, role, and schema added to the string. It would look something like this.

jdbc:snowflake://[URI instance to connect to]?user=[theUser]&password=[superSecretPassword]&warehouse=[THE_WAREHOUSE]&db=[the_db]&role=[role_like_PUBLIC]&schema=[schema_to_use]

Once those steps are done, click on Connect Database.

From there, you can select tables and query against those tables just like you would in any Hasura GraphQL API connected database. Let’s say, for example, you want to query a band along with the band’s albums. That query would look something like this, with the inferred nested object of albums returning as an array.

query artistAlbums {
  CHINOOK_PUBLIC_ARTIST(where: {NAME: {_eq: "Metallica"}}) {
    NAME
    artistAlbums {
      TITLE
    }
  }
}

The result would then come back with the array of album titles for the particular artist Metallica.

{
  "data": {
    "CHINOOK_PUBLIC_ARTIST": [
      {
        "NAME": "Metallica",
        "artistAlbums": [
          {
            "TITLE": "Garage Inc. (Disc 1)"
          },
          {
            "TITLE": "Black Album"
          },
          {
            "TITLE": "Garage Inc. (Disc 2)"
          },
          {
            "TITLE": "Kill 'Em All"
          },
          {
            "TITLE": "Load"
          },
          {
            "TITLE": "Master Of Puppets"
          },
          {
            "TITLE": "ReLoad"
          },
          {
            "TITLE": "Ride The Lightning"
          },
          {
            "TITLE": "St. Anger"
          },
          {
            "TITLE": "...And Justice For All"
          }
        ]
      }
    ]
  }
}

Correlative data across disparate tables within reporting tables are difficult requests to process. With Hasura connected to Snowflake, users can easily add relationships between tables to bring data together into a single GraphQL Query.

A tactical example can be seen with the relationship shown in the console here. In this example, we have a music library database where we are trying to define a relationship between the Artist and Albums table.

Hasura connects the Artist table to the Album table so that a relationship can traverse either direction when querying.

The following query shows how a nested query works based on that relationship, adding power to queries when working with Snowflake. Users now have multiple queries issued from a singular GraphQL query. Thereby reducing your query complexity, keeping the number of client calls minimal, and improving the readability of your code base.

Adding caching is extremely easy. For example, using the query listed above, we can add the directive as shown.

query artistAlbums @cached {
  CHINOOK_PUBLIC_ARTIST(where: {NAME: {_eq: "Metallica"}}) {
    NAME
    artistAlbums {
      TITLE
    }
  }
}

Join our webinar on Jan 13

We are hosting a live webinar on this topic on Jan 13, 2023, where we will do a technical deep dive on the connector, cover use cases, and more with a live demo. It’s a great opportunity to connect live with the technical team behind this capability. Register here.

Want to see a custom demo sooner? Get in touch with our team by signing up here. Put in “Snowflake demo” in the notes, along with more context of your use case for Hasura+Snowflake.

What’s Coming Next

A reminder, this is the beta release, and we’re moving quickly to add new functionality for Snowflake as well as support for additional connectors. In the coming months, we’ll be building features like GraphQL mutation support for our API, and Snowflake will be one of the first connectors to receive that update.

If you’d like to discuss Snowflake, request new features, or just ask questions about Hasura and Snowflake, join our Discord.

Building a Digital Twin with MQTT and Hasura Streaming Subscriptions

Hasura — Tue, 06 Dec 2022 03:50:01 +0000

In this blog we will be talking about how to build a digital twin of a toy car with an android phone (to leverage sensors), MQTT broker and Hasura GraphQL Engine.

We will go over,

Building a digital twin of a toy car attached with a gyroscope sensor through an android device
Setting up the device to stream real time sensor data to an MQTT Broker.
Receiving data from the MQTT broker and sending it as a GraphQL mutation to Hasura GraphQL engine.
Consume live data on the ReactJS application with Hasura GraphQL subscriptions
Rendering the real time gyroscope sensor data as a 3D car model using ThreeJS

What is a Digital Twin?

A digital twin is a virtual representation of a real-world physical system or product (a physical twin) that serves as the digital counterpart of it for practical purposes, such as system simulation, integration, testing, monitoring, and maintenance.

Digital Twins are created in a way that it can receive sensor data in real time from the physical counterpart. This allows the twin to simulate the physical object in real time to learn about the characteristics of the physical twin. There are systems that also have controllers to remotely manage and maintain the system in real time.

It is also used to remotely debug large machinery, with the help of mixed reality gears- this ease out the need of skilled technicians to travel across the globe and save time and cost.

Digital Twins are mainly used in

Manufacturing
Automobiles
Power Generation
Healthcare
Industry 4.0
Town planning
Remote Debugging

Building a Digital Twin

The basic requirements to build a digital twin are

Physical object (a toy car in this case)
Sensors to collect data (will be using an android device) & Controllers
Connectivity to the central system (Internet)
Server that manages the data flow and control events (Hasura GraphQL Engine & MQTT Broker)
Virtual Representation (a static web application, using ThreeJS to render 3D in this case)

Note : The repository is available here and the commands mentioned in the steps are configured in the repository.

Setup a Physical Thing

As shown above, we can have a toy car and an android phone attached to it.

The android device attached to the device will be able to collect real time sensor data (Gyroscope in this case) and send it to the cloud.

Streaming data to Cloud

Considering most of the real world IoT systems use low footprint transfer protocols to send data from device to server communication, we will be using MQTT as the preferred protocol here.

We can also use GraphQL over HTTP from this point itself, but considering the current systems and integrations this demo will talk about consuming and ingesting data from end devices to MQTT Broker and then to a Postgres DB through a Hasura instance.

To simplify the end device implementation, we will be using the android application MQTT Simulator to collect and send rotational data to an MQTT broker.

Receiving Data

MQTT follows a topic based pub-sub pattern, and it requires a broker to handle this.

For the demo purpose, let’s use HiveMQ public MQTT broker so that we don’t need any setup here.

If you use the above application, the data will be streaming to digital_twin/android/<provided_device_id> by default and this can be listened easily by subscribing to the same topic or digital_twin/android/#. # here will make sure any topic name that starts with the pattern will be subscribed.

At this point, we have successfully received the data from the device to the internet/network, we now need a way to store this data and stream the data to the clients who require live data from the device.

Now we need a place to store and access the data in a secure way, to do this we will be using Hasura GraphQL Engine backed with a postgres DB.

Setting up Hasura and Postgres DB

Deploy to Hasura

Open Hasura Console, head to Data tab and connect a Postgres DB if not done already.
Head to Data->SQL tab to create a table.

CREATE TABLE "public"."device_data"("id" serial NOT NULL, "data" jsonb NOT NULL, "timestamp" timestamptz NOT NULL, "device_id" text NOT NULL, PRIMARY KEY ("id") );

Track the table device_data so that it can be accessed through GraphQL APIs.

Consuming MQTT data and sending to Hasura

We need a NodeJS runtime to consume data from the MQTT runtime and send it to Hasura. I have a small NodeJS script that does the following,

Subscribe to the MQTT broker with the same channel name used by the Android MQTT Simulator
Parse the MQTT payload and transform the data

client.on("message", function (topic, message) {
 // message is Buffer, convert this to generate GraphQL mutation from the message
 const decoded = getMutation(message.toString(), topic);
 sendToHasura(decoded, CONSTANTS.HASURA_HOST);
});

GraphQL mutations (as shown below) on Hasura GraphQL Engine to store it on the DB.

mutation AddDeviceData($data: jsonb!, $device_id: String!, $timestamp: timestamptz!) {
 insert_device_data_one(object: {data: $data, device_id: $device_id, timestamp: $timestamp}) {
   id
 }
}

At this point we successfully managed to get the data to the postgres instance and the data flow will looks like the following

To start this service,

clone the project from https://github.com/soorajshankar/digital-twin-graphql
Change .env file with your project configuration
Run the command yarn connect or npm run connect

This command will connect to MQTT broker and start subscribing to the channel mentioned in the env file.

You could also use the public MQTT broker (HiveMQ) used in the repository for testing purpose.

Streaming Live Data to the Dashboard

From this part we will be discussing the ReactJS application and the main functionalities.

When you connect a postgres table on Hasura, you automatically get a GraphQL Subscription API to listen to the live changes. We will be using the latest streaming subscription feature from Hasura to stream the live data.

In this case, the query looks like the following:

subscription GetDeviceData($timestamp: timestamptz) {
   device_data_stream(
     batch_size: 1
     cursor: { initial_value: { timestamp: $timestamp }, ordering: ASC }
     where: { device_id: { _eq: "android" } }
   ) {
     data
     device_id
     id
     timestamp
   }
 }

Here is how the streaming subscription work in general:

Visualization

Visualizing data is very important in the connected world as it can save a lot of time to understand, make decisions and act on it. The concept of Digital Twin plays a great role in simplifying this task to an extent. Both human and simulated environments can process the data much faster when it is virtualized in a digital environment.

To do this we will be using ThreeJS model to visualize the toy car, the car model orientation will refresh frequently with the latest data stream.

Download demo video

Repo: https://github.com/soorajshankar/digital-twin-graphql

Summary

Even though we built a digital twin of a toy car, this can be made useful for variety of use cases like

Connected cars
Remote Monitoring : Windmills, Smart Factories, Industry 4.0 and other Industrial IoT systems
Remote Debugging with AR goggles and connected data.

Also if you have an existing data stream/ queue, it can easily be connected to Hasura GraphQL to set up a secure and easy way to store and access realtime data until the end consumer.

Next.js 13 Nested Layouts, Streaming SSR with Realtime GraphQL

Hasura — Tue, 22 Nov 2022 12:47:23 +0000

Next.js, the open-source React framework by Vercel, has released version 13, laying the foundations to be dynamic without limits. Please read their release blog post for an excellent overview.

In this post, we will build a mini e-commerce store where you can view the products on sale, order one, and see a real-time feed of orders. We are covering new Next.js features such as:

Nested Layouts
Data Fetching
Streaming and Suspense
Client and Server Components

We also see how to integrate with Hasura GraphQL for realtime features such as Streaming Subscriptions.

Let’s dive in with the e-commerce schema from the Hasura Super App. See our Data Hub for instructions on how to import the schema into Hasura.

The source code is available on GitHub.

Next.js Setup

Create a Next.js TypeScript application. As of this blog post, we will use the experimental version because that allows us to use beta features.

npx create-next-app@latest --experimental-app

Install the dependencies

npm install @graphql-codegen/cli @graphql-codegen/client-preset @graphql-typed-document-node/core dotenv graphql graphql-request graphql-ws

Replace the contents of next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,
    runtime: "experimental-edge",
  },
  images: {
    remotePatterns: [
      {
        protocol: "http",
        hostname: "img6a.flixcart.com",
      },
      {
        protocol: "http",
        hostname: "img5a.flixcart.com",
      },
    ],
  },
};

module.exports = nextConfig;

The experimental-edge runtime lets us use Vercel's edge runtime. The term “Edge” refers to the orientation toward instant serverless compute environments and not a specific set of locations. The image section configures Next.js's image component to use pictures from our e-commerce store.

Our last step is adding two entries to .env.local

NEXT_PUBLIC_HASURA_GRAPHQL_URL=<Hasura GraphQL endpoint>
NEXT_PUBLIC_HASURA_GRAPHQL_WS_URL=<Hasura websocket endpoint>

If your Hasura instance has an admin secret, you can also set HASURA_GRAPHQL_ADMIN_SECRET for use in the code generator.

GraphQL Code Generator Setup

When making TypeScript applications with GraphQL we highly recommend using GraphQL Code Generator. Combined with the graphql-request library, we have fully typed queries and mutations by the magic of code generation!

Create a file codegen.ts

import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  overwrite: true,
  schema: [
    {
      [process.env.NEXT_PUBLIC_HASURA_GRAPHQL_URL!]: {
        headers: {
          // If you have an admin secret set
          "x-hasura-admin-secret": process.env.HASURA_GRAPHQL_ADMIN_SECRET!,
        },
      },
    },
  ],
  config: {
    skipTypename: true,
    enumsAsTypes: true,
    scalars: {
      numeric: "number",
    },
  },
  documents: "lib/service/queries.graphql",
  generates: {
    "lib/gql/": {
      preset: "client",
      config: {},
      plugins: [],
    },
  },
};

export default config;

This config connects to our Hasura GraphQL instance and generates typings based on the client preset.

In package.json add a script to load environment variables and run the code generator "codegen": "graphql-codegen --require dotenv/config --config codegen.ts dotenv_config_path=./.env.local"

Next, define our queries/mutations in lib/service/queries.graphql

query GetProducts {
  product(limit: 10) {
    id
    name
  }
}

query GetProduct($id: Int!) {
  product_by_pk(id: $id) {
    id
    description
    name
    price
    image_urls(path: "$[0]")
  }
}

mutation PlaceOrder($products: order_product_arr_rel_insert_input!) {
  insert_order_one(
    object: {
      products: $products
      billing_address_id: 222
      user_id: 225
      shipping_address_id: 222
    }
  ) {
    id
  }
}

Finally, run the generator:

npm run codegen

graphql-request Setup

Create a graphql-request client in lib/service/client.ts

import { GraphQLClient } from "graphql-request";

export const gqlClient = new GraphQLClient(
  process.env.NEXT_PUBLIC_HASURA_GRAPHQL_URL!,
  { fetch }
);

We pass in the environment’s global fetch, so our Next.js will work anywhere, regular Node.js or an edge runtime.

Nested Layouts

One of the new Next.js features is nested layouts. They allow us to have a shared parent component, and the router can render in child routes.

To demonstrate this, we will display ten products on our home page. When you click on one, it will navigate the right-hand side to the product details page.

Fetch Home Page Data

Next.js 13 uses React’s new way of fetching data. Read more about the RFC on Github. We will use it to get a list of products.

In app/layout.tsx, we add an async function to get data from Hasura:

import Link from "next/link";
import { GetProductsDocument } from "../lib/gql/graphql";
import { gqlClient } from "../lib/service/client";
import "./globals.css";

async function getProducts() {
  const { product: products } = await gqlClient.request(
    GetProductsDocument,
    {}
  );
  return products;
}

We call it in our component using async/await, then create an unordered list of product links:

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const products = await getProducts();
  return (
    <html lang="en">
      <head />
      <body>
        <main style={{ display: "flex" }}>
          <section style={{ minWidth: "400px", width: "400px" }}>
            <ul>
              {products.map((product) => (
                <li key={product.id}>
                  <Link href={`/${product.id}`}>{product.name}</Link>
                </li>
              ))}
            </ul>
          </section>
          <section style={{ flexGrow: 1 }}>{children}</section>
        </main>
      </body>
    </html>
  );
}

With nested layouts and a layout.tsx file, the URL will control the component output in {children}.

Product Details Page

We will now add a Next.js page that gets the product ID from the URL and fetches/displays the details.

Create app/[id]/page.tsx. The [id] means we will pass down data from the URL as a prop named id:

import Image from "next/image";
import { GetProductDocument } from "../../lib/gql/graphql";
import { gqlClient } from "../../lib/service/client";

async function getProduct(id: number) {
  const { product_by_pk } = await gqlClient.request(GetProductDocument, { id });
  return product_by_pk!;
}

export default async function Page({
  params: { id },
}: {
  params: { id: string };
}) {
  const product = await getProduct(Number(id));
  return (
    <>
      <h1>{product.name}</h1>
      <Image
        src={product.image_urls}
        alt={`${product.name} Picture`}
        width={200}
        height={200}
      ></Image>
      <div>{`$${product.price.toFixed(2)}`}</div>
      <p>{product.description}</p>
    </>
  );
}

Now when you click a link on the left, you should see the product details page appear on the right!

Streaming and Suspense

Streaming and Suspense are new React features that allow us to instantly display a loading UI, then stream in UI once data fetching is done.

As an example of this, create app/loading.tsx:

export default function Loading() {
  // You can add any UI inside Loading, including a Skeleton.
  return <div>loading</div>;
}

Now when you try navigating between products you should see the loading UI before the details are loaded.

Client Components

All the stuff we've built so far uses Server Components which means they render on the server and don't need to ship JS to the browser.

However, sometimes we need to create Client Components that have logic on the browser. For our example, we will have a button that orders a product and a Hasura Streaming Subscription that shows us a real-time list of orders.

For our real-time subscription, we'll use the graphql-ws library. For the mutation we will continue to use graphql-request.

We create a new client component in app/components/orders.tsx using the syntax we are used to in React. The only new thing part is the "use client"; at the top which tells Next.js this is a client component.

"use client";

import { useEffect, useState } from "react";
import { PlaceOrderDocument } from "../../lib/gql/graphql";
import { createClient } from "graphql-ws";
import { gqlClient } from "../../lib/service/client";

const wsClient = createClient({
  url: process.env.NEXT_PUBLIC_HASURA_GRAPHQL_WS_URL!,
});

export default function Orders({ id }: { id: number }) {
  const [orders, setOrders] = useState<
    Array<{ id: number; created_at: string; quantity: number }>
  >([]);

  useEffect(() => {
    const unsubscribe = wsClient.subscribe(
      {
        query: `
          subscription ProductOrders($id: Int!) {
            order_product_stream(
              batch_size: 10
              cursor: { initial_value: { created_at: "2021-02-22T18:16:12.95499+00:00" } }
              where: { product_id: { _eq: $id } }
            ) {
              id
              quantity
              created_at
            }
          }`,
        variables: {
          id,
        },
      },
      {
        next: ({ data }) => {
          setOrders((orders) => [
            ...orders,
            ...(data?.order_product_stream as any),
          ]);
        },
        error: (error) => {
          console.log(error);
        },
        complete: () => {
          console.log("complete");
        },
      }
    );
    return () => {
      unsubscribe();
    };
  }, [id]);

  return (
    <>
      <button
        onClick={async () =>
          await gqlClient.request(PlaceOrderDocument, {
            products: { data: [{ product_id: id, quantity: 1 }] },
          })
        }
      >
        Order
      </button>
      <li>
        {orders.map((order) => (
          <li key={order.id}>
            {`Order ${order.id} created at ${new Date(order.created_at)}`}
          </li>
        ))}
      </li>
    </>
  );
}

When a new order comes from the subscription we update useState and render out the list of orders. When we click on the button, we trigger a GraphQL mutation to add a new order.

Now back in app/[id]/page.tsx we import the component and add it to the end of the page

import Orders from "../components/orders";

export default async function Page({
  params: { id },
}: {
  params: { id: string };
}) {
  const product = await getProduct(Number(id));
  return (
    <>
      ...
      <Orders id={Number(id)}></Orders>
    </>
  );
}

When we navigate to the product detail page you should now be able to order a product and see new orders pop up in real-time!

Conclusion

Next.js is packed with new features and deep integration with cutting-edge React techniques. Combined with Hasura, we can easily make great applications for our users!

Hasura Actions using Netlify Functions for Custom Logic

Hasura — Wed, 16 Nov 2022 15:07:02 +0000

In this guide, we will show how to write your own Hasura actions using Netlify functions (with your own custom business logic or a third-party API integration). But first, definitions.

What are Hasura actions?

Hasura provides support for integrating our own business logic or third-party APIs (usually REST APIs) with the help of “Hasura Actions”. Learn more about Hasura Actions.

What are Netlify functions?

Netlify functions are AWS’s serverless lambda functions that allow you to define your business logic and functions as an API and expose them with an endpoint. Click here to learn more about netlify functions.

How to write your own Hasura Actions using Netlify functions?

This guide will go through the process in three parts, feel free to skip to the part that is more interesting for you.

Part I: Create a Function in an app
Part II: Define the functions with logic
Part III: Add the function to Hasura using Actions

Note: Hasura Actions can also be used to add REST endpoints to Hasura’s GraphQL schema.

Part I: Create a Function in an app

To create a function in the app, install the netlify-cli package from npm (preferably as global).

npm install -g netlify-cli

Once the netlify-cli is installed, go to the project’s root folder, and link your Netlify site to the folder. Click here to learn more about linking sites in Netlify.

netlify link

Once linked, type the following command to create a function.

netlify functions:create

You will see a list of predefined templates. Choose the “hello-world” template.

The function will be created in <project-root>/netlify/functions/hello-world/hello-world.js

Part II: Define the functions with logic

Here is an example of a Netlify function for Hasura's Actions, which checks if an email is present in the DB without exposing all the users to the client.

const axios = require("axios");

const hgeEndpoint = "https://example.hasura.app/v1/graphql";
const adminSecret = "adminSecret";

const handler = async (event) => {
  let request;
  try {
    request = JSON.parse(event.body);
  } catch (error) {
    // Make sure you add code and message to errors. These will be shown in the hasura console errors.
    let response = {
      status: false,
      code: "api/parse-error",
      message: "error",
      error: { message: "cannot parse input" },
    };
    return { statusCode: 400, body: JSON.stringify(response) };
  }

  if (!request.input.email) {
    // Make sure you add code and message to errors. These will be shown in the hasura console errors.
    let response = {
      status: false,
      message: "Please send email",
      code: "input/undefined",
      error: { message: "Please send email" },
    };
    return { statusCode: 400, body: JSON.stringify(response) };
  }

  let query = {
    query: `
      query check_user($email: String) {
        users(where: {email: {_eq: $email}}) {
          id
          email_id
        }
      }
    `,
    variables: { email: request.input.email },
  };

  try {
    let result = await axios.post(hgeEndpoint, query, {
      headers: { "x-hasura-admin-secret": adminSecret },
    });
    if (result.data.users.length > 0) {
      let response = {
        status: true,
        message: "success",
        user: data.data.users,
      };
      return { statusCode: 200, body: JSON.stringify(response) };
    } else {
      // Make sure you add code and message to errors. These will be shown in the hasura console errors.
      let response = {
        status: false,
        code: "user/not-found",
        message: "No user found",
        error: { message: "No user found" },
      };
      return { statusCode: 400, body: JSON.stringify(response) };
    }
  } catch (error) {
    let response = {
      status: false,
      code: "api/fetch-error",
      message: error.message,
      error: { message: error.message, detail: error.toString() },
    };
    return { statusCode: 500, body: JSON.stringify(response) };
  }
};

module.exports = { handler };

NOTE: Add the code and message to the response body.

These are displayed in Hasura’s GraphQL errors (whenever the API is returning an error in Hasura, they follow the GraphQL error standard).

The error in Hasura is displayed like this:

Error state in Hasura GraphQL

Part III: Add the function to Hasura using Actions

Once the custom business logic is created as an API using Netlify functions, add it to Hasura using Actions as follows:

Login to your Hasura console and go to the “Actions” tab
Click on the “Create” button
Define the inputs and outputs of your API as shown below. (Learn more about the GraphQL inputs & outputs on Hasura)
Add the endpoint of your Netlify function under the Handler.

Creating an Action

Note: You can also modify the permission of the actions if you’re using role-based permissions.

Try out the Actions using Hasura’s GraphQL API Explorer

The success state on Hasura’s API Explorer from the Netlify functions will look like this:

Success state of an action

The error state on Hasura’s API Explorer from the Netlify functions will look like this:

There are two error states

When the user is not found with the requested email, you’ll see the following (User not found in DB error)

When the email is not sent along with the request, you’ll see the following (Validation Error)

Input not given / undefined error

DEV Community: Hasura

The complexity of building a GraphQL API permissions layer and how Hasura solves this

Introduction

Key items to consider

Data modeling

Roles and attributes

Nested rules

Performance

Predicate pushdown

Building a DIY authorization layer for a GraphQL API

Why is building an authorization layer complex?

Parsing and validating JWT token

Passing context

API-wide authorization

Resolver-level authorization

GraphQL schema-based authorization

How does Hasura’s authorization layer work?

Declarative

Fine-grained access control

Easily integrate with your authentication system

Predicate pushdown

Cross-source authorization

OWASP Top 10

Try out Hasura

Save Time and Stop Writing GraphQL Resolvers

Writing the GraphQL Resolvers manually

N+1 problem

Security Rules

Adding gateway features

Save time and resources

Building GraphQL APIs without writing resolvers

How does that work

Adding custom business logic

Remote Schemas

Hasura Actions

Event Triggers

Summary

Announcing Pod42, the Hasura ChatGPT Bot

Getting started with Pod42

Testing for fun

Disclaimer

GraphQL Security in Production with Automated Allow Lists

Enable "Allow List"

Allow List of operations in Hasura

Another way to create an AllowList

Automatically Generate an AllowList

The rise of GraphQL APIs on data warehouses

TL;DR

Table of Contents

The rise of data warehouse integrations

Top use cases for data warehouse integration

GraphQL Data APIs are the solution to data warehouse integration

Building APIs the traditional way can be slow and expensive

Building and scaling GraphQL and REST APIs faster with Hasura

Streaming Subscriptions

Performance

Caching

High performance GraphQL to SQL Engine

Security

Row level and column level permissions

Get started with instant API on your data warehouse

Best Practices Guide for GraphQL Observability with Hasura [Part 1]

Observability

SLOs, SLIs, and the Three Pillars

The Three Pillars of Observability

Metrics

Request Rate

How to Use

Error Rate

How to Use

Viewing Individual Errors

Average Request Execution Time

How to Use

Subscriptions

How to Use

Logs

Aggregating by Query Name

Diagnosing Errors

Distributed Tracing

External API Tracing