Skip to content

Getting Started

Create a new Spring Boot application

The DGS framework is based on Spring Boot, so get started by creating a new Spring Boot application if you don't have one already. The Spring Initializr is an easy way to do so. You can use either Gradle or Maven, Java 8 or newer or use Kotlin. We do recommend Gradle because we have a really cool code generation plugin for it!

The only Spring dependency needed is Spring Web.

Spring initializr

Open the project in an IDE (Intellij recommended).

Adding the DGS Framework Dependency

Add the dependency to your Gradle or Maven configuration. dgs version:

repositories {

dependencies {
    implementation ""
repositories {

dependencies {
    <!-- Make sure to set the latest framework version! -->
NOTE: The DGS Framework requires Kotlin 1.4, and does not work with Kotlin 1.3. Older Spring Boot versions may bring in Kotlin 1.3.

Creating a Schema

The DGS framework is designed for schema first development. The framework picks up any schema files in the src/main/resources/schema folder. Create a schema file in: src/main/resources/schema/schema.graphqls.

type Query {
    shows(titleFilter: String): [Show]

type Show {
    title: String
    releaseYear: Int

This schema allows querying for a list of shows, optionally filtering by title.

Implement a Data Fetcher

Data fetchers are responsible for returning data for a query. Create two new classes example.ShowsDataFetcher and Show and add the following code. Note that we have a Codegen plugin that can do this automatically, but in this guide we'll manually write the classes.

public class ShowsDatafetcher {

    private final List<Show> shows = List.of(
            new Show("Stranger Things", 2016),
            new Show("Ozark", 2017),
            new Show("The Crown", 2016),
            new Show("Dead to Me", 2019),
            new Show("Orange is the New Black", 2013)

    public List<Show> shows(@InputArgument String titleFilter) {
        if(titleFilter == null) {
            return shows;

        return -> s.getTitle().contains(titleFilter)).collect(Collectors.toList());

public class Show {
    private final String title;
    private final Integer releaseYear   ;

    public Show(String title, Integer releaseYear) {
        this.title = title;
        this.releaseYear = releaseYear;

    public String getTitle() {
        return title;

    public Integer getReleaseYear() {
        return releaseYear;
class ShowsDataFetcher {
    private val shows = listOf(
        Show("Stranger Things", 2016),
        Show("Ozark", 2017),
        Show("The Crown", 2016),
        Show("Dead to Me", 2019),
        Show("Orange is the New Black", 2013))

    fun shows(@InputArgument titleFilter : String?): List<Show> {
        return if(titleFilter != null) {
            shows.filter { it.title.contains(titleFilter) }
        } else {

    data class Show(val title: String, val releaseYear: Int)

That's all the code needed, the application is ready to be tested!

Test the app with GraphiQL

Start the application and open a browser to http://localhost:8080/graphiql. GraphiQL is a query editor that comes out of the box with the DGS framework. Write the following query and tests the result.

    shows {

Note that unlike with REST, you have to specifically list which fields you want to get returned from your query. This is where a lot of the power from GraphQL comes from, but a surprise to many developers new to GraphQL.

The GraphiQL editor is really just a UI that uses the /graphql endpoint of your service. You could now connect a UI to your backend as well, for example using React and the Apollo Client.

Next steps

Now that you have a first GraphQL service running, we recommend improving this further by doing the following: