Creating a New GraphQL Endpoint in GMS
This guide will walk you through how to add a new GraphQL endpoint in GMS.
listOwnershipTypes example: The
listOwnershipTypes
endpoint will be used as an example. This endpoint was added in this commit which can be used as reference.
GraphQL API changes
Adding an endpoint definition
GraphQL endpoint definitions for GMS are located in the datahub-graphql-core/src/main/resources/
directory. New endpoints can be added to the relevant file, e.g. entity.graphql
for entity management endpoints, search.graphql
for search-related endpoints, etc. Or, for totally new features, new files can be added to this directory.
listOwnershipTypes example: The endpoint was added in the
entity.graphql
file since ownership types are being added as an entity.
Query or Mutation?
Read-only functionality can go in the Query
section, while mutations go in the Mutation
section. The definition for new functionality can go in the appropriate section depending on the use case.
listOwnershipTypes example: The endpoint was added in the
type Query
section because it is read-only functionality. In the same commit,createOwnershipType
,updateOwnershipType
, anddeleteOwnershipType
were added in thetype Mutation
section as these are operations that perform writes.
Input and Output Types
If the new endpoint requires more than a few inputs or outputs, a struct can be created in the same file to collect these fields.
listOwnershipTypes example: Since this functionality takes and returns quite a few parameters,
input ListOwnershipTypesInput
andtype ListOwnershipTypesResult
were added to represent the input and output structs. In the same PR, no input and output structs were added fordeleteOwnershipType
since the inputs and output are primitive types.
Building your changes
After adding the new endpoint, and new structs if necessary, building the project will generate the Java classes for the new code that can be used in making the server changes. Build the datahub project to make the new symbols available.
listOwnershipTypes example: The build step will make the new types
ListOwnershipTypesInput
andListOwnershipTypesResult
available in a Java IDE.
Java Server changes
We turn now to developing the server-side functionality for the new endpoint.
Adding a resolver
GraphQL queries are handled by Resolver
classes located in the datahub-graphql-core/src/main/java/com/linkedin/datahub/graphql/resolvers/
directory. Resolvers are classes that implement the DataFetcher<T>
interface where T
is CompletableFuture<ClassForResultOfTheEndpoint>
.This interface provides a get
method that takes in a DataFetchingEnvironment
and returns a CompletableFuture
of the endpoint return type. The resolver can contain any services needed to resolve the endpoint, and use them to compute the result.
listOwnershipTypes example: The
ListOwnershipTypesResolver
class implementsDataFetcher<CompletableFuture<ListOwnershipTypesResult>>
since this is the return type of the endpoint. It contains anEntityClient
instance variable to handle the ownership type fetching.
Often the structure of the Resolver
classes is to call a service to receive a response, then use a method to transform the result from the service into the GraphQL type returned.
listOwnershipTypes example: The
ListOwnershipTypesResolver
calls thesearch
method in itsEntityClient
to get the ownership types, then calls the definedmapUnresolvedOwnershipTypes
function to transform the response into aListOwnershipTypesResult
.
Tip: Resolver classes can be tested with unit tests!
listOwnershipTypes example: The reference commit adds the
ListOwnershipTypeResolverTest
class.
Adding the resolver to the GMS server
The main GMS server is located in GmsGraphQLEngine.java
. To hook up the resolver to handle the endpoint, find the relevant section based on if the new enpoint is a Query
or a Mutation
and add the resolver as the dataFetcher
for the name of the endpoint.
listOwnershipTypes example: The following line of code is added in
GmsGraphQLEngine
:.dataFetcher("listOwnershipTypes", new ListOwnershipTypesResolver(this.entityClient))
. This uses theListOwnershipTypes
resolver to handle queries forlistOwnershipTypes
endpoint.
Testing your change
In addition to unit tests for your resolver mentioned above, GraphQL functionality in datahub can be tested using the built-in GraphiQL endpoint. The endpoint is located at localhost:8080/api/graphiql
on Quickstart and at the equivalent URL for a production instance. This provides fast debug-ability for querying GraphQL. See How to Set Up GraphQL for more information