GraphQL is an important evolution in the design of Application Performance Interfaces (API), but even today it can be difficult to know how to get started with GraphQL, how to move beyond "Getting Started" with GraphQL, and how to move beyond the conventional wisdom on GraphQL. This is especially true for Java. This guide attempts to cover all these bases in three steps. First, I'll tell you what GraphQL is, and as a bonus I'll tell you what GraphQL really is. Second, I'll show you how to implement state-of-the-art GraphQL in Java for a real application. Third, I'll offer you an alternative path beyond the state-of-the-art that may suit your needs better in every dimension. And, if you feel like skipping to the end, who am I to stop you? It certainly will save a great deal of effort.

So, what is GraphQL? Well, GraphQL.org says

GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. GraphQL isn’t tied to any specific database or storage engine and is instead backed by your existing code and data.

That's not wrong, but let me take a few more runs at it from different directions. Sure, GraphQL is "a query language for your API", but you might as well just say that it is an API, or a way of building an API. That puts it in contrast with REST, which GraphQL is an evolution from and an alternative to. GraphQL offers several improvements over REST (or at least, the way that REST is usually done):

expressivity

A client can say exactly what data they need from a server, no more and no less.

efficiency

Expressivity leads to efficiency gains, reducing network chatter and wasted bandwidth.

discoverability

In order to know what to say to a server, a client needs to know what can be said to a server. That's where discoverability comes in, allowing data consumers to know exactly what's available from data producers.

simplicity

GraphQL puts clients in the driver's seat, so there had better be some good ergonomics for driving. GraphQL's highly-regular machine-readable syntax, simple execution model, and simple specification lend themselves to inter-operable and composable tools:

• query tools
• schema registries
• gateways
• code generators
• client libraries

But, what else is GraphQL. What really is GraphQL? GraphQL is also a data model for its query language and, despite the name, neither the query language nor the data model are very "graphy." The data model is essentially just JSON. The query language looks like JSON and can be boiled down to a few simple features:

types

A type is a simple value (a scalar) or a set of fields (an object). While you naturally introduce new types for your own problem domain, there are few special types (called Operations). One of theses is Query, which is the root of requests for data (setting aside Subscription for now, for the sake of simplicity). A type essentially is a set of rules for determining if a piece of data–or a request for that piece of data–validly conforms to the given type. A GraphQL type is very much like a user-defined type in programming languages like C++, Java, and Typescript, and is very much like a table in a relational database.

field

A field within one type contains one or more pieces of data that validly conform to another type, thus establishing relationships among types. A GraphQL field is very much like a property of a user-defined type in a programming language, and is very much like a column in a relational database. Relationships between GraphQL types are very much like pointers or references in programming languages, and are very much like foreign key constraints in relational databases.

There's more to GraphQL, but that's pretty much the essence. Note the similarities between concepts in GraphQL and in programming languages, and especially between concepts in GraphQL and in relational databases. That will be important later.

OK, that's enough for now about what GraphQL is, but what is GraphQL for? Why should we consider GraphQL, especially as an alternative to REST? I listed above some of GraphQL's improvements over typical REST–expressivity, efficiency, discoverability, simplicity–but another perhaps more concise way to put it is this:

GraphQL's expressivity, efficiency, discoverability, and simplicity make life easier for data consumers.

However, there's a corollary:

GraphQL's expressivity, efficiency, discoverability, and simplicity make life harder for data producers.

That's you! If you're a Java programmer working with GraphQL, your job is probably to produce GraphQL API servers for clients to consume (there are relatively few–not "none", but "few"–settings for Java on the client). Offering all that expressivity, discoverability, etc. ain't easy, so how do you do it?

On the journey to providing a GraphQL API we confront a series interdependent choices, which can make life easier (or harder) for data producers. One choice is over just how "expressive, efficient, discoverable, and simple" is our API, but let's set that aside for a moment and treat that as an emergent property of the other choices we make. Life is about trade-offs, after all.

Another choice is over build-versus-buy [PDF]​, but let's also set that aside for a moment, accept that we're building a GraphQL API server (in Java), explore how that is done, and evaluate the consequences.

If we're building a GraphQL API server in Java, another choice is over whether to build it completely from scratch or to use libraries and frameworks, and if the latter then which libraries and frameworks to use. Let's set that aside, rightfully regard a complete DIY solution as pointless masochism, and survey the landscape of Java libraries and frameworks for GraphQL. As of writing (April 2024) there are three important interdependent players in this space:

graphql-java

graphql-java is a lower-level foundational library for working with GraphQL in Java, which began in 2015. Since the other players depend on and use graphql-java, consider graphql-java to be non-optional. Another crucial choice is whether you are or are not using the Spring Boot framework. If you're not using Spring Boot then stop here! 🛑 Since this is a prerequisite, in the parlance of the ThoughtWorks Radar this is unavoidably Adopt.

Netflix DGS

DGS is a higher-level library for working with GraphQL in Java with Spring Boot, which began in 2021. If you're using DGS then you will also be using graphql-java under-the-hood, but typically you won't come into contact with graphql-java. Instead, you will be sprinkling annotations throughout the Java code to identify the code segments (called "resolvers" or "data fetchers"…more on that later) that execute GraphQL requests. Thoughtworks said Trial as of 2023 for DGS but this is a dynamic space and their opinion may have changed. I say Hold, for reasons given below.

Spring for GraphQL

Spring for GraphQL is another higher-level library for working with GraphQL in Java with Spring Boot, which began around 2023, and is also based on annotations. It may be too new for ThoughtWorks, but it's not too new for me. I say adopt, and read on for why.

The makers of Spring for GraphQL say:

It is a joint collaboration between the GraphQL Java team and Spring engineering…It aims to be the foundation for all Spring, GraphQL applications.

Translation:

The Spring team has a privileged collaboration with the makers of the foundational library for GraphQL in Java, and intends to "win" in this space.

Moreover, the makers of Netflix DGS have much to say on the subject of that library's relationship to Spring for GraphQL.

Soon after we open-sourced the DGS framework, we learned about parallel efforts by the Spring team to develop a GraphQL framework for Spring Boot. The Spring GraphQL project was in the early stages at the time and provided a low-level of integration with graphql-java. Over the past year, however, Spring GraphQL has matured and is mostly at feature parity with the DGS Framework. We now have 2 competing frameworks that solve the same problems for our users.

Today, new users must choose between the DGS Framework or Spring GraphQL, thus missing out on features available in one framework but not the other. This is not an ideal situation for the GraphQL Java community.

For the maintainers of DGS and Spring GraphQL, it would be far more effective to collaborate on features and improvements instead of having to solve the same problem independently. Finally, a unified community would provide us with better channels for feedback.

The DGS framework is widely used and plays a vital role in the architecture of many companies, including Netflix. Moving away from the framework in favor of Spring-GraphQL would be a costly migration without any real benefits.

From a Spring Framework perspective, it makes sense to have an out-of-the-box GraphQL offering, just like Spring supports REST.

Translation:

If you're a Spring Boot shop already using DGS, go ahead and keep using it for now. If you're a Spring Boot shop starting afresh, you should probably just use Spring for GraphQL.

In this guide I've told you what GraphQL is. I've told you what GraphQL really is. I've set the stage by giving some background on the relevant libraries and frameworks in Java. Now, let me show you how to implement state-of-the-art GraphQL in Java for a real application, and since we're starting afresh we'll take the advice from DGS and just use Spring for GraphQL.

Opinions are free to differ on what it even means to be a "real application." For the purpose of this guide, what I mean by "real application" in this settings is an application that has at least these features:

persistence

Many tutorials, getting-started guides, and overviews only address in-memory data models, stopping well short of interacting with a database. This guide shows you some ways to cross this crucial chasm and discusses some of the consequences, challenges, and trade-offs involved. This is a vast topic so I barely scratch the surface, but it's a start. The primary goal is to support Query operations. A stretch goal is to support Mutation operations. Subscription operations are thoroughly off-the-table for now.

flexibility

I wrote above that just how expressive, efficient, discoverable, and simple we make our GraphQL API is technically a choice we make, but is practically a property that emerges from other choices we make. I also wrote that building GraphQL API servers is difficult for data producers. Consequently, many data producers cope with that difficulty by dialing way back on those other properties of the API. Many GraphQL API servers in the real world are inflexible, are superficial, are shallow, and are in many ways "GraphQL-in-name-only." This guide shows some of what's involved in going beyond the status quo and how that comes into tension with other properties, like efficiency. Spoiler Alert: It isn't pretty.

efficiency

In fairness, many GraphQL API servers in the real world achieve decent efficiency, albeit at the expense of flexibility, by essentially encoding REST API endpoints into a shallow GraphQL schema. The standard approach in GraphQL is the data-loader pattern, but few tutorials really show how this is used even with an in-memory data model let alone with a database. This guide offers one implementation of the data loader pattern to combat the N+1 problem. Again, we see how that comes into tension with flexibility and simplicity.

modernity

Anyone writing a Java application that accesses a database will have to make choices about how to access a database. That could involve just JDBC and raw SQL (for a relational database) but arguably the current industry standard is still to use an Object-Relational Mapping (ORM) layer like Hibernate, jooq, or the standard JPA. Getting an ORM to play nice with GraphQL is a tall order, may not be prudent, and may not even be possible. Few if any other guides touch this with a ten-foot-pole. This guide at least makes an attemp will make an attempt with an ORM in the future!

The recipe I follow in this guide for building a GraphQL API server in Java for a relational database is the following:

1. Choose Spring Boot for the overall server framework.
2. Choose Spring for GraphQL for the GraphQL-specific parts.
3. Choose Spring Data for JDBC for data access in lieu of an ORM for now.
4. Choose Maven over Gradle because I prefer the former. If you choose the latter, you're on your own.
5. Choose PostgreSQL for the database. Most of the principles should apply for pretty much any relational database, but you've got to start somewhere.
6. Choose Docker Compose for orchestrating a development database server. There are other ways of bringing in a database, but again, you've got to start somewhere.
7. Choose the Chinook data model. Naturally, you will have your own data model, but Chinook is a good choice for illustration purposes because it's fairly rich, has quite a few tables and relationships, goes well beyond the ubiquitous but trivial To-Do apps, is available for a wide variety of databases, and is generally well-understood.
8. Choose the Spring Initializr for bootstrapping the application. There's so much ceremony in Java, any way to race through some of it is welcomed.
9. Create a GraphQL schema file. This is a necessary step for graphql-java, for DGS, and for Spring for GraphQL. Weirdly, the Spring for GraphQL overview seems to overlook this step, but the DGS "Getting Started" guide is there to remind us. Many "thought leaders" will exhort you to isolate your underlying data model from your API. Theoretically, you could do this by having different GraphQL types from your database tables. Practically, this is a source of busy-work.
10. Write Java model classes, one for every GraphQL type in the schema file and every table in the database. You're free to make other choices for this data model or for any other data model, and you can even write code or SQL views to isolate your underlying data model from your API, but do ask how important this really is when the number of tables/classes/types grows to the hundreds or thousands.
11. Write Java controller classes, with one method at least for every root field. In practice, this is the bare minimum. There probably will be many more. By the way, these methods are your "resolvers".
12. Annotate every controller class with @Controller to tell Spring to inject it as a Java Bean that can serve network traffic.
13. Annotate every resolver/data-fetcher method with @SchemaMapping or QueryMapping to tell Spring for GraphQL how to execute the parts of a GraphQL operation.
14. Implement those resolver/data-fetcher methods by whatever means necessary to mediate interactions with the database. In version 0, this will be just simple raw SQL statements.
15. Upgrade some of those resolver/data-fetcher methods by replacing @SchemaMapping or @QueryMapping with @BatchMapping. This latter annotation signals to Spring for GraphQL that we want make the execution more efficient by combating the N+1 problem, and we're prepared to pay the price in more code in order do do it.
16. Refactor those @BatchMapping-annotated methods to support the data loader pattern, by accepting (and processing) a list of identifiers for related entities, rather than a single identifier for a single related entity.
17. Write copious test-cases for every possible interaction.
18. Just use a fuzz-tester on the API and call it a day.

That is a long recipe above! Instead of going into chapter-and-verse for every single step, in this guide I do two things. First, I provide a public repository with working code that is easy to use, easy to run, easy to read, and easy to understand. If you feel it falls short in any of these objects please do let me know! Second, I highlight some of the important steps, put them in context, discuss the choices involved, and offer some alternatives.

version: "3.6"
services:
  postgres:
    image: postgres:16
    ports:
      - ${PGPORT:-5432}:5432
    restart: always
    environment:
      POSTGRES_PASSWORD: postgres
      PGDATA: /var/lib/pgdata
    volumes:
      - ./initdb.d-postgres:/docker-entrypoint-initdb.d:ro
      - type: tmpfs
        target: /var/lib/pg/data

mkdir -p ./initdb.d-postgres
wget -O ./initdb.d-postgres/04_chinook_ddl.sql
wget -O ./initdb.d-postgres/05_chinook_genres_artists_albums.sql
wget -O ./initdb.d-postgres/06_chinook_songs.sql

docker compose up -d

docker-compose up -d

psql "postgresql://postgres:postgres@localhost:5432/postgres" -c '\d'

              List of relations
 Schema |      Name       | Type  |  Owner   
--------+-----------------+-------+----------
 public | Album           | table | postgres
 public | Artist          | table | postgres
 public | Customer        | table | postgres
 public | Employee        | table | postgres
 public | Genre           | table | postgres
 public | Invoice         | table | postgres
 public | InvoiceLine     | table | postgres
 public | MediaType       | table | postgres
 public | Playlist        | table | postgres
 public | PlaylistTrack   | table | postgres
 public | Track           | table | postgres
 public | account         | table | postgres
 public | account_summary | view  | postgres
 public | order           | table | postgres
 public | order_detail    | table | postgres
 public | product         | table | postgres
 public | region          | table | postgres
(17 rows)

type Query {
  Artist(limit: Int): [Artist]
  ArtistById(id: Int): Artist
  Album(limit: Int): [Album]
  AlbumById(id: Int): Album
  Track(limit: Int): [Track]
  TrackById(id: Int): Track
  Playlist(limit: Int): [Playlist]
  PlaylistById(id: Int): Playlist
  PlaylistTrack(limit: Int): [PlaylistTrack]
  PlaylistTrackById(id: Int): PlaylistTrack
  Genre(limit: Int): [Genre]
  GenreById(id: Int): Genre
  MediaType(limit: Int): [MediaType]
  MediaTypeById(id: Int): MediaType
  Customer(limit: Int): [Customer]
  CustoemrById(id: Int): Customer
  Employee(limit: Int): [Employee]
  EmployeeById(id: Int): Employee
  Invoice(limit: Int): [Invoice]
  InvoiceById(id: Int): Invoice
  InvoiceLine(limit: Int): [InvoiceLine]
  InvoiceLineById(id: Int): InvoiceLine
}

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

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

type Customer {
  CustomerId   : Int
  FirstName    : String
  LastName     : String
  Company      : String
  Address      : String
  City         : String
  State        : String
  Country      : String
  PostalCode   : String
  Phone        : String
  Fax          : String
  Email        : String
  SupportRepId : Int
  SupportRep   : Employee
  Invoices     : [Invoice]
}

  package com.graphqljava.tutorial.retail.models;

  public class ChinookModels {
      public static
          record Album
          (
           Integer AlbumId,
           String Title,
           Integer ArtistId
           ) {}

      public static
          record Artist
          (
           Integer ArtistId,
           String Name
           ) {}

      public static
          record Customer
          (
           Integer CustomerId,
           String FirstName,
           String LastName,
           String Company,
           String Address,
           String City,
           String State,
           String Country,
           String PostalCode,
           String Phone,
           String Fax,
           String Email,
           Integer SupportRepId
           ) {}
  ...
}

package com.graphqljava.tutorial.retail.controllers; // It's got to go into a package somewhere.

import java.sql.ResultSet;      // There's loads of symbols to import.
import java.sql.SQLException;   // This is Java and there's no getting around that.
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.graphql.data.ArgumentValue;
import org.springframework.graphql.data.method.annotation.BatchMapping;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.SchemaMapping;
import org.springframework.jdbc.core.RowMapper;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.jdbc.core.simple.JdbcClient.StatementSpec;
import org.springframework.stereotype.Controller;

import com.graphqljava.tutorial.retail.models.ChinookModels.Album;
import com.graphqljava.tutorial.retail.models.ChinookModels.Artist;
import com.graphqljava.tutorial.retail.models.ChinookModels.Customer;
import com.graphqljava.tutorial.retail.models.ChinookModels.Employee;
import com.graphqljava.tutorial.retail.models.ChinookModels.Genre;
import com.graphqljava.tutorial.retail.models.ChinookModels.Invoice;
import com.graphqljava.tutorial.retail.models.ChinookModels.InvoiceLine;
import com.graphqljava.tutorial.retail.models.ChinookModels.MediaType;
import com.graphqljava.tutorial.retail.models.ChinookModels.Playlist;
import com.graphqljava.tutorial.retail.models.ChinookModels.PlaylistTrack;
import com.graphqljava.tutorial.retail.models.ChinookModels.Track;


public class ChinookControllers { // You don't have to nest all your controllers in one file. It's just what I do.
    @Controller public static class ArtistController { // Tell Spring about this controller class.
        @Autowired JdbcClient jdbcClient; // Lots of ways to get DB access from the container.  This is one way in Spring Data.
        RowMapper<Artist>                 // I'm not using an ORM, and only a tiny bit of help from Spring Data.
            mapper = new RowMapper<>() {  // Consequently, there are these RowMapper utility classes involved.
                    public Artist mapRow (ResultSet rs, int rowNum) throws SQLException {
                        return
                        new Artist(rs.getInt("ArtistId"),
                                   rs.getString("Name"));}};
        @SchemaMapping Artist Artist (Album album) { // @QueryMapping when we can, @SchemaMapping when we have to
            return                                   // Here, we're getting an Artist for a given Album.
                jdbcClient
                .sql("select * from \"Artist\" where \"ArtistId\" = ? limit 1") // Simple PreparedStatement wrapper
                .param(album.ArtistId()) // Fish out the relating field ArtistId and pass it into the PreparedStatement
                .query(mapper)           // Use our RowMapper to turn the JDBC Row into the desired model class object.
                .optional()              // Use optional to guard against null returns!
                .orElse(null);}
        @QueryMapping(name = "ArtistById") Artist // Another resolver, this time to get an Artist by its primary key identifier
            artistById (ArgumentValue<Integer> id) { // Note the annotation "name" parameter, when the GraphQL field name doesn't match exactly the method name
            for (Artist a : jdbcClient.sql("select * from \"Artist\" where \"ArtistId\" = ?").param(id.value()).query(mapper).list()) return a;
            return null;}
        @QueryMapping(name = "Artist") List<Artist> // Yet another resolver, this time to get a List of Artists.
            artist (ArgumentValue<Integer> limit) { // Note the one "limit" parameter.  ArgumentValue<T> is the way you do this with GraphQL for Java.
            StatementSpec
                spec = limit.isOmitted() ? // Switch SQL on whether we did or did not get the limit parameter.
                jdbcClient.sql("select * from \"Artist\"") :
                jdbcClient.sql("select * from \"Artist\" limit ?").param(limit.value());
            return              // Run the SQL, map the results, return the List.
                spec
                .query(mapper)
                .list();}}
...

query {
  Artist(limit: 10) {
    ArtistId
    Album {
      AlbumId
      Track {
        TrackId
      }
    }
  }
}

@BatchMapping(field = "Albums") public Map<Artist, List<Album>> // Switch to @BatchMapping
    albumsForArtist (List<Artist> artists) { // Take in a List of parents rather than a single parent
    return
        jdbcClient
        .sql("select * from \"Album\" where \"ArtistId\" in (:ids)") // Use a SQL "in" predicate taking a list of identifiers
        .param("ids", artists.stream().map(x -> x.ArtistId()).toList()) // Fish the list of identifiers out of the list of parent objects
        .query(mapper)  // Can re-use our usual mapper
        .list()
        .stream().collect(Collectors.groupingBy(x -> artists.stream().collect(Collectors.groupingBy(Artist::ArtistId)).get(x.ArtistId()).getFirst()));
    // ^ Java idiom for grouping child Albums according to their parent Albums
}

We saw that the "easy way" of building GraphQL servers is the one typically offered in tutorials and "Getting Started" guides, and is over tiny unrealistic in-memory data models, without a database.

We saw that the "real way" of building GraphQL servers (in Java) described in some detail above, regardless of library or framework, involves:

• writing schema file entries, possibly for every table
• writing Java model classes, possibly for every table
• writing Java resolver methods, possibly for every field in every table
• eventually writing code to solve arbitrarily complex compositions of input parameters
• writing code to budget SQL operations efficiently

We also observe that GraphQL lends itself to a "recursive divide-and-conquer with an accumulator approach": a GraphQL query is recursively divided and sub-divided along type and field boundaries into a "graph", internal nodes in the graph are processed individually by resolvers, but the data are passed up the graph dataflow style, accumulating into a JSON envelope that is returned to the user. The GraphQL libraries are decomposing the incoming queries into something like an Abstract Syntax Tree (AST), firing SQL statements for all the internal nodes (ignoring the data loader pattern for a moment), then re-composing the data. And, we are its willing accomplices!

We also observe that building GraphQL servers according to the above recipes leads to other outcomes:

• lots of repetition
• lots of boilerplate code
• bespoke servers
• that are tied to a particular data model

Build a GraphQL server more than once according to the above recipes and you will make these observations. Making these observations, you will naturally feel a powerful urge to build more sophisticated abstractions that reduce the repetition, reduce the boilerplate, generalize the servers, and decouple them from any particular data model. This is what I call the "natural way" of building a GraphQL API, as it's a natural evolution from the trivial "easy way" of tutorials and "Getting Started" guides, and from the cumbersome "real way" of resolvers and even data loaders.

Building a GraphQL server with a network of nested resolvers offers some flexibility and dynamism, and requires a lot of code. Adding in more flexibility and dynamism with limits, pagination, filtering, and sorting, requires more code still. And while it may be dynamic, it will also be very chatty with the database, as we saw. Reducing the chattiness necessitates composing the many fragmentary SQL statements into fewer SQL statements which individually do more work. That's what the data loader pattern does: it reduces the number of SQL statements from "a few tens" to "less than 10 but more than 1". In practice, that may not be a huge win and it comes at the cost of developer time and lost dynamism, but it is a step down the path of generating fewer, more sophisticated queries. The terminus of that path is "1": the optimal number of SQL statements (ignoring caching) is 1. Generate one giant SQL statement that does all the work of fetching the data, teach it to generate JSON while you're at it, and this is the best you will ever do with a GraphQL server (for a relational database). It will be hard work, but you can take solace that having done it once, it need not ever be done again if you do it right, by introspecting the database to generate the schema.

Do that, and what you will build won't be so much a "GraphQL API server" as a "GraphQL to SQL compiler." If that gives you pause, consider that this is what you were already doing all along, anyway. The easy way, the real way, the natural way: they're all both necessarily GraphQL to SQL compilers! They just lie along a spectrum of versatility, flexibility, and efficiency. Acknowledge that building a GraphQL to SQL compiler is what you were doing all along, embrace that fact, and lean into it, and you may never need to build another GraphQL server again. What could be better than that?

One thing that could be better than building your last GraphQL server, or your only GraphQL server, is never building a GraphQL server in the first place. After all, your goal wasn't to build a GraphQL API, but rather to have a GraphQL API. The easiest way to have a GraphQL API is just to go get one. Get one for free if you can. Buy one if the needs justify it. This is the final boss on the journey of GraphQL maturity.

You don't literally need to buy a GraphQL server. You can, and there can be good reasons to do so in some settings, but there are other options. What I really mean to address is the decision over whether or not to build a GraphQL server. In some cases, this may be warranted, but in most cases it is not.

It does depend on the data sources involved. If there are PostgreSQL databases or PostgreSQL-ish databases for which we want APIs, then we are blessed with many fine choices.

First, in this case it pays to consider whether or not we truly need a GraphQL API. How do we decide if we need a GraphQL API? Of course, there's no right answer, but the following considerations are useful guide.

Are your data consumers humans or machines?

If they're machines you DO NOT need GraphQL.

Similarly, are you serving ETL use cases?

If you're performing ETL you DO NOT need GraphQL.

Do you have primarily analytical workloads?

If you're serving analytical workloads you DO NOT need GraphQL.

Do you have a public, semi-public, or private API?

Well, it depends.

Public

You MAY have GraphQL. GraphQL is a good choice for fully public freely-available APIs because of its flexibility, efficiency, and especially its discoverability. You will have to take steps to secure the API against DoS attacks (rate limits, time limits, query complexity limits, throttling) but probably not against exfiltration or tampering. You probably won't need query white-listing and you probably won't want to turn off GraphQL introspection queries. Tampering probably won't be an issue as typically these are read-only APIs. In any case, when you cannot anticipate the range of queries, GraphQL is a good choice.

Semi-public

You MAY have GraphQL. GraphQL is a good choice for semi-public APIs, such as those secured by credentials, subject to authorization, and open only to select customers and partners, but still operating over the open internet. Denial-of-Service (DoS) attacks are still a threat, though less so, but now exfiltration and especially tampering are bigger concerns. Like with a public API, if you cannot anticipate the full range of queries and other operations, GraphQL is a good choice.

Private

You MAY NOT NEED GraphQL. This is the most interesting case to me. In this setting, the clients are typically developed in-house. A firm's "back-end" teams supply APIs that are used by the same firm's "front-end" teams. API calls may still go over the open internet, as with a mobile app, but they're typically "baked-in" with the app. The range of API calls is finite and known in advance. In this case, there's little need for GraphQL discoverability and even flexibility, at least in the production environment. You can and should disable introspection queries, and you should consider white-listing. At this point, however, it throws into question the value of a GraphQL API. If you know all of the operations in advance you MAY just use REST!

With those considerations in mind, we return to the subject of acquiring an API server over building one, and in that case which one to acquire. If you don't need a GraphQL API–perhaps because you have private API needs, you may stick with REST. If you have PostgreSQL or PostgreSQL-ish databases, PostgREST is a very good open-source choice.

If you do need a GraphQL API, and you are on PostgreSQL, then PostGraphile is another very good open-source choice.

If you add other databases to the mix, however, the choices narrow considerably. Hasura Community Edition is a good choice, but unfortunately that Open-Source version only works with PostgreSQL. If you are not constrained by free tools, however, Hasura Enterprise expands support to include Microsoft SQL Server, MySQL, Oracle, and a host of other databases.

What I'd like you to take away from this article are these things.

• GraphQL is a general-purpose query language, like SQL.
• GraphQL is less powerful than SQL.
• GraphQL is simpler than SQL.
• But, that simplicity and diminution of power make it good for web APIs.
• GraphQL is meant for humans.
• Therefore, don't use GraphQL for ETL.
• GraphQL is meant for transactional workloads.
• Therefore, don't use GraphQL for analytical or OLAP.
• GraphQL is useful for public and semi-public APIs.
• Consider treating GraphQL just as a development tool for private APIs.
• But then for private APIs, you might as well just substitute SQL for development.
• If you do go with GraphQL, seriously consider acquiring a GraphQL server rather than building one.
• To acquire a GraphQL server, you're on firmest ground if you're using PostgreSQL.
• If you go with building a GraphQL server and you're using Java, this guide is a good start.
• For that case, I go well beyond the usual tutorials and "Getting Started" guides to get you started building a real server in Java.
• However, strap yourself in. It's a lot of work.
• You will write a lot of boilerplate, in schema files, model files, controller files, and maybe ORM mapping files.
• Consequently, resist lectures about "not exposing your data model" because doing anything else for a large data model is a ton of work.
• Probably resist an pressure internal or external to use an ORM. It probably won't help and will only hurt.
• Adding expressivity to your GraphQL API–the raison d'etre of GraphQL–requires a lot of work.
• Nominally, that expressivity also comes at the cost of efficiency and performance.
• That lost efficiency and performance is known as the "N+1 problem."
• However, the N+1 problem is probably way overblown for APIs that serve humans (see above).
• If you're starting a GraphQL server in Java, and you're not using Spring Boot, choose graphql-java and stop there.
• If you're starting a GraphQL server in Java, and you ARE using Spring Boot, prefer Spring for GraphQL over Netflix DGS.