{"id":13565473,"url":"https://github.com/Jotschi/vertx-graphql-example","last_synced_at":"2025-04-03T22:31:33.212Z","repository":{"id":141892874,"uuid":"84472143","full_name":"Jotschi/vertx-graphql-example","owner":"Jotschi","description":"Vert.x Server which exposes a GraphQL API","archived":false,"fork":false,"pushed_at":"2018-10-18T09:05:49.000Z","size":331,"stargazers_count":29,"open_issues_count":0,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-04T19:41:31.401Z","etag":null,"topics":["graphql","graphql-java","orientdb","vertx","vertx-web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jotschi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2017-03-09T17:51:42.000Z","updated_at":"2023-07-17T14:24:54.000Z","dependencies_parsed_at":"2023-03-12T12:15:18.111Z","dependency_job_id":null,"html_url":"https://github.com/Jotschi/vertx-graphql-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jotschi%2Fvertx-graphql-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jotschi%2Fvertx-graphql-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jotschi%2Fvertx-graphql-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jotschi%2Fvertx-graphql-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jotschi","download_url":"https://codeload.github.com/Jotschi/vertx-graphql-example/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247090248,"owners_count":20881939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","graphql-java","orientdb","vertx","vertx-web"],"created_at":"2024-08-01T13:01:47.694Z","updated_at":"2025-04-03T22:31:33.207Z","avatar_url":"https://github.com/Jotschi.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Vert.x GraphQL Example\n\nThis example shows how to build a basic GraphQL endpoint using [Vert.x](http://vertx.io/) and [OrientDB](http://orientdb.com/orientdb/)\n\n## Getting Started\n\n* Clone example project\n```\ngit clone git@github.com:jotschi/vertx-graphql-example.git\ncd vertx-graphql-example\n```\n\n* Import the project into your IDE \n\n* Start the Vert.x web server by running GraphQLServer.java\nAccess http://localhost:3000/browser/ in your browser or use this \n[Example Query](http://localhost:3000/browser/?query=%7B%0A%20%20movies%20%7B%0A%20%20%20%20title%0A%20%20%7D%0A%20%20hero%20%7B%0A%20%20%20%20name%0A%20%20%20%20friends%20%7B%0A%20%20%20%20%20%20name%0A%20%20%20%20%20%20friends%20%7B%0A%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A)\n\n## Motivation\n\nI recently added GraphQL support to [Gentics Mesh](https://getmesh.io) and I thought it would be a good idea to boil down the essence of my implementation in example so that I could share it in a simpler form.\nThis example will not cover all aspects that I have added to the Gentics Mesh API (e.g. paging, search and error handling) but it will give you a basic overview of the parts that I put together.\nGraphQL does not require a GraphDB even if the name might suggest it. Using a graphdb in combination with GraphQL does nevertheless provide you with some advantages which I will highlight later on.\n\n## Why StarWars?\n\nMost graphql examples which I found make use of that domain model. I adoped the graphql-java demo schema and added some values.\n\n## Contents\n\n### GraphiQL browser\n\nThe [GraphiQL browser](https://github.com/graphql/graphiql) is served via a StaticHandler. No further configuration is needed.\n\n### Data setup\n\nThe `StarWarsData` class contains the demo data. The demo data is structured in a very simple graph. A central root element is used to reference the aggregation vertices which list all the basic elements (humans, droids, planets, movies).\nAdditional edges exist between those elements.\n\nThis example does not use SQL to interface with the GraphDB. Instead it uses makes use of the Object Graph Mapper library [Ferma 3.x](https://github.com/Syncleus/Ferma). This library allowed me to create basic Java classes which map to the vertices which I later use within my Graph. \nFerma helps a lot if you plan to setup your graph domain model. \nUsing a tinkerpop based native API is in most cases the fastest way to interact with the GraphDB. OrientDB nativly supports this API and thus the overall overhead is minimal compared to SQL.\n\n### GraphQL schema\n\nThe GraphQL schema defines which fields and objects can be resolved via a query.\nI use [graphql-java](https://github.com/graphql-java/graphql-java) to setup the schema and process the query.\n\nThe `StarWarsSchema` class contains all schema fields and object definitions.\nAny field may define a data fetcher which is used to access the graph database and load the needed data. Data fetchers can access the the graphql query context (in our case the StarWarsRoot vertex) and a source element. The context will not change if you access nested elements but the source element can change. This is very useful since you can just pass along a vertex. This vertex can be processed by another data fetcher and related vertices, edges or a single vertex can be returned. You can create a very fast and efficient API if you model your graph relationships in a way that it matches up closely to your graphql schema.\n\n### Executing queries\n\nThe `GraphQLVerticle` contains the whole query execution logic.\n\nThe query is wrapped in an JSON string and thus needs to unwrapped first.\n\nThe `handleQuery` method processes the query. It is important to note that the query \nhas a starting point. In our case this is the root vertex.\n\n```java\nExecutionInput input = new ExecutionInput(query, null, queryJson, demoData.getRoot(), extractVariables(queryJson));\ntx.complete(graphQL.execute(input));\n```\n\nAll GraphQL schema data fetchers can access this root vertex and use it as a starting point for the graph traversals.\n\n### Testing GraphQL\n\nThere are many ways to test a GraphQL API. You could write unit tests which individually test each graphql type or just test the data fetchers.\nI often opt for tests which cover a big portion of application stack. Those tests have the advantage that they have the potential to uncover bugs which reside in the areas between application parts. The downside is that they often take much longer to execute.\n\nThe `GraphQLTest` which is part of the example loads a predefined GraphQL query and executes it by posting it to the graphql endpoint. The graphQL query also contains special comments which are parsed. These parsed comments are used to perform assertions against the response query.\n\n```\n{\n    vader: human(id: 1001) {\n\t\t# [$.data.vader.name=Darth Vader]\n\t\tname\n    }\n}\n\n```\n\nThe comment contains a basic json-path and expected value for that path.\n\n### Whats next? What did you not cover?\n\n* I have not covered mutation support. (GraphQL write operations). \n* I did not cover async graphql execution. It may be desireable to execute parts of the graphql query in-parallel to speedup processing.\n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJotschi%2Fvertx-graphql-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJotschi%2Fvertx-graphql-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJotschi%2Fvertx-graphql-example/lists"}