{"id":20796719,"url":"https://github.com/vertx-howtos/graphql-howto","last_synced_at":"2026-02-27T22:10:36.341Z","repository":{"id":46074472,"uuid":"185364121","full_name":"vertx-howtos/graphql-howto","owner":"vertx-howtos","description":"Building a GraphQL server","archived":false,"fork":false,"pushed_at":"2024-12-02T17:41:30.000Z","size":547,"stargazers_count":11,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-06T15:51:42.475Z","etag":null,"topics":["graphql","howto","vertx"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vertx-howtos.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-05-07T09:04:50.000Z","updated_at":"2024-12-02T17:41:34.000Z","dependencies_parsed_at":"2022-09-03T22:11:02.156Z","dependency_job_id":"40d91042-aa46-4fc4-8892-8316b17d0e1e","html_url":"https://github.com/vertx-howtos/graphql-howto","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vertx-howtos/graphql-howto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgraphql-howto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgraphql-howto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgraphql-howto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgraphql-howto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vertx-howtos","download_url":"https://codeload.github.com/vertx-howtos/graphql-howto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgraphql-howto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29917217,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"ssl_error","status_checked_at":"2026-02-27T19:37:41.463Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphql","howto","vertx"],"created_at":"2024-11-17T16:28:49.827Z","updated_at":"2026-02-27T22:10:36.324Z","avatar_url":"https://github.com/vertx-howtos.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Implementing a GraphQL server\n:page-permalink: /\n:page-github: vertx-howtos/graphql-howto\n\nifdef::env-github[]\nimage:https://github.com/vertx-howtos/graphql-howto/workflows/Publish%20the%20how-to/badge.svg[\"Build Status\", link=\"https://github.com/vertx-howtos/graphql-howto/actions?query=workflow%3A%22Publish+the+how-to%22\"]\nendif::env-github[]\n\nThis document will show you how to implement a GraphQL server.\n\n== What you will build\n\nYou will build a GraphQL server to manage your personal tasks (a.k.a. the todo list).\n\nThe application consists in a few files:\n\n. the `tasks.graphqls` schema file\n. the `Task` data class\n. the `GraphQLVerticle` class\n\n== What you need\n\n* A text editor or IDE\n* Java 17 or higher\n* Maven or Gradle\n\n== Create a project\n\nThe code of this project contains Maven and Gradle build files that are functionally equivalent.\n\n=== Using Maven\n\nHere is the content of the `pom.xml` file you should be using:\n\nifdef::env-github[]\nlink:pom.xml[Maven POM file]\nendif::env-github[]\nifndef::env-github[]\n[source,xml,role=\"collapsed\"]\n.Maven `pom.xml`\n----\ninclude::pom.xml[]\n----\nendif::env-github[]\n\n=== Using Gradle\n\nAssuming you use Gradle with the Kotlin DSL, here is what your `build.gradle.kts` file should look like:\n\nifdef::env-github[]\nlink:build.gradle.kts[Gradle build file]\nendif::env-github[]\nifndef::env-github[]\n[source,kotlin,role=\"collapsed\"]\n.Gradle `build.gradle.kts`\n----\ninclude::build.gradle.kts[]\n----\nendif::env-github[]\n\n== Managing tasks with Vert.x Web and GraphQL\n\n=== Creating the schema\n\nFirst things first, let's create a GraphQL schema for the task management app:\n\nifdef::env-github[]\nlink:src/main/resources/tasks.graphqls[GraphQL Schema]\nendif::env-github[]\nifndef::env-github[]\n[source]\n.GraphQL Schema `src/main/resources/tasks.graphqls`\n----\ninclude::src/main/resources/tasks.graphqls[]\n----\nendif::env-github[]\n\nThe schema defines:\n\n* the `Task` _type_ with 3 fields: `id`, `description` and `completed`\n* the `allTasks` _query_ that returns an array of tasks and optionally takes a parameter `uncompletedOnly` (defaults to `true`)\n* the `complete` _mutation_ that takes the task `id` as parameter and returns a _boolean_ indicating whether the operation was successful\n\n=== Implementing the server\n\nIn the application, tasks will be modeled by the `Task` class:\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/graphql/Task.java[Task class]\nendif::env-github[]\nifndef::env-github[]\n[source,java,role=\"collapsed\"]\n.Java `src/main/java/io/vertx/howtos/graphql/Task.java`\n----\ninclude::src/main/java/io/vertx/howtos/graphql/Task.java[]\n----\n\u003c1\u003e a random identifier is assigned when a `Task` instance is created\nendif::env-github[]\n\nIMPORTANT: The `Task` class field names must match those of the corresponding GraphQL schema type.\n\nOn startup, we shall create a few items:\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[GraphQLVerticle initData method]\nendif::env-github[]\nifndef::env-github[]\n[source,java,role=\"collapsed\"]\n.Java `src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java`\n----\ninclude::src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[tag=initData]\n----\nendif::env-github[]\n\nThen the https://www.graphql-java.com/[GraphQL-Java] engine must be setup:\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[GraphQLVerticle setupGraphQL method]\nendif::env-github[]\nifndef::env-github[]\n[source,java,role=\"collapsed\"]\n.Java `src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java`\n----\ninclude::src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[tag=setupGraphQL]\n----\n\u003c1\u003e Read the schema file from classpath\n\u003c2\u003e `TypeDefinitionRegistry` is the GraphQL-Java runtime equivalent to the schema file definitions\n\u003c3\u003e `RuntimeWiring` tells GraphQL-Java how to resolve types and fetch data\n\u003c4\u003e `GraphQLSchema` connects the runtime type definitions with the type resolvers and data fetchers\n\u003c5\u003e Create the application's `GraphQL` engine\nendif::env-github[]\n\nSo far, so good.\nNow how does one implement a data fetcher?\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[GraphQLVerticle allTasks method]\nendif::env-github[]\nifndef::env-github[]\n[source,java,role=\"collapsed\"]\n.Java `src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java`\n----\ninclude::src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[tag=allTasks]\n----\nendif::env-github[]\n\nThe `allTasks` data fetcher gets the `uncompletedOnly` parameter from the `DataFetchingEnvironment`.\nIts value is either provided by the client or, as defined in the schema file, set to `true`.\n\nWARNING: Do not block the Vert.x event loop in your data fetchers.\nIn this how-to, the data set is small and comes from memory, so it's safe to implement `allTasks` in a blocking fashion.\nWhen working with databases, caches or web services, make sure your data fetcher returns a `CompletionStage`.\nFor further details, please refer to the https://vertx.io/docs/vertx-web-graphql/java/[The Vert.x Web GraphQL Handler documentation].\n\nThe code for the `complete` mutation is not much different:\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[GraphQLVerticle complete method]\nendif::env-github[]\nifndef::env-github[]\n[source,java,role=\"collapsed\"]\n.Java `src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java`\n----\ninclude::src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[tag=complete]\n----\nendif::env-github[]\n\nIt gets the `id` parameter provided by the client, then looks up for the corresponding task.\nIf a task is found, it is updated and the mutation returns `true` to indicate success.\n\nAlmost there!\nNow let's put things together in the verticle `start` method:\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[GraphQLVerticle start method]\nendif::env-github[]\nifndef::env-github[]\n[source,java,role=\"collapsed\"]\n.Java `src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java`\n----\ninclude::src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[tag=start]\n----\n\u003c1\u003e Create Vert.x Web GraphQL handler for the GraphQL-Java object\n\u003c2\u003e Define a _catch-all_ Vert.x Web route and set the `BodyHandler` (required to handle `POST` requests bodies)\n\u003c3\u003e Define a Vert.x Web route for GraphQL queries and set the GraphQL handler\nendif::env-github[]\n\n== Running the application\n\nThe `GraphQLVerticle` needs a `main` method:\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[GraphQLVerticle main method]\nendif::env-github[]\nifndef::env-github[]\n[source,java,role=\"collapsed\"]\n.Java `src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java`\n----\ninclude::src/main/java/io/vertx/howtos/graphql/GraphQLVerticle.java[tag=main]\n----\n\u003c1\u003e Create a `Vertx` context\n\u003c2\u003e Deploy `GraphQLVerticle`\n\nThen you can run the application:\n\n* straight from your IDE or,\n* with Maven: `mvn compile exec:java`, or\n* with Gradle: `./gradlew run` (Linux, macOS) or `gradlew run` (Windows).\n\nThe following examples use the https://httpie.org/[HTTPie] command line HTTP client.\nPlease refer to the https://httpie.org/doc#installation[installation] documentation if you don't have it installed on your system yet.\n\n=== Listing uncompleted tasks\n\nTo list uncompleted tasks, open your terminal and execute this:\n\n[source,shell]\n----\nhttp :8080/graphql query='\nquery {\n  allTasks {\n    id,\n    description\n  }\n}'\n----\n\nYou should see something like:\n\n[source,javascript]\n----\n{\n    \"data\": {\n        \"allTasks\": [\n            {\n                \"description\": \"Learn GraphQL\",\n                \"id\": \"4a9f53fd-584f-4169-b725-6b320043db8b\"\n            },\n            {\n                \"description\": \"Profit\",\n                \"id\": \"03770db5-a8ad-44b3-ad6e-6fe979015088\"\n            },\n            {\n                \"description\": \"Build awesome GraphQL server\",\n                \"id\": \"6b000f72-8aa9-4f4e-9539-5da2ab11cd94\"\n            }\n        ]\n    }\n}\n----\n\n=== Completing a task\n\nTo complete the _Learn GraphQL_ task:\n\n[source,shell]\n----\nhttp :8080/graphql query='\nmutation {\n  complete(id: \"4a9f53fd-584f-4169-b725-6b320043db8b\")\n}'\n----\n\nNOTE: The `id` used in the query above must be changed to the value generated by your application.\n\nAfter the task is completed, you will see:\n\n[source,javascript]\n----\n{\n    \"data\": {\n        \"complete\": true\n    }\n}\n----\n\n=== Retrieving all tasks\n\nIf you need to retrieve all tasks, including those already completed, make sure to set the `uncompletedOnly` parameter to `false` in the `allTasks` query:\n\n[source,shell]\n----\nhttp :8080/graphql query='\nquery {\n  allTasks(uncompletedOnly: false) {\n    id\n    description\n    completed\n  }\n}'\n----\n\nThe expected output is:\n\n[source,javascript]\n----\n{\n    \"data\": {\n        \"allTasks\": [\n            {\n                \"completed\": true,\n                \"description\": \"Learn GraphQL\",\n                \"id\": \"4a9f53fd-584f-4169-b725-6b320043db8b\"\n            },\n            {\n                \"completed\": false,\n                \"description\": \"Profit\",\n                \"id\": \"03770db5-a8ad-44b3-ad6e-6fe979015088\"\n            },\n            {\n                \"completed\": false,\n                \"description\": \"Build awesome GraphQL server\",\n                \"id\": \"6b000f72-8aa9-4f4e-9539-5da2ab11cd94\"\n            }\n        ]\n    }\n}\n----\n\n== Summary\n\nThis document covered:\n\n. the Vert.x Web GraphQL Handler setup,\n. implementing simple query and mutation data fetchers.\n\n== See also\n\n- https://www.graphql-java.com/documentation/getting-started[The GraphQL-Java documentation]\n- https://vertx.io/docs/vertx-web-graphql/java/[The Vert.x Web GraphQL Handler documentation]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fgraphql-howto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvertx-howtos%2Fgraphql-howto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fgraphql-howto/lists"}