client_faq

• Configuring the GraphQL client
  • Define the GraphQL server URL
  • Connect to an OAuth2 protected server
  • Change the generated code (custom templates)
• Questions about GraphQL request execution
  • HowTo retrieve the extensions GraphQL response field
  • Execution of a request with all parameters set in the String request

Configuring the GraphQL client

Define the GraphQL server URL

The way to define the GraphQL server endpoint varies, depending on the kind of app you uses:

For Spring app, you'll update the application.properties or application.yml file, for instance:

graphql.endpoint.url = http://localhost:8180/my/updated/graphql/path

For non Spring app, you'll define the GraphQL server endpoint with one of these ways:

• Call the static com.graphql_java_generator.client.request.AbstractGraphQLRequest.setStaticConfiguration(GraphQLConfiguration) method, directly, or through GraphQLRequest that you've got from the query, mutation or subscription class (see the Execute GraphQL Requests page for more info on getting a GraphQLRequest.
  • As this method is static, this configuration is then available for all your GraphQLRequests. This is nice if you attack only one GraphQL server.
• Call the setInstanceConfiguration(GraphQLConfiguration) method of your GraphQLRequest that you've got from the query, mutation or subscription class (see the Execute GraphQL Requests page for more info on getting a GraphQLRequest.
  • This allows to define various configuration, depending on your GraphQLRequests, including calling several GraphQL servers.
• Create your query, mutation or subscription executor instance, from the generated code. For instance, if your GraphQL schema defines a QueryType, you can create an instance of it like this: QueryTypeExecutor executor = new QueryTypeExecutor("https://your.server.com/your/graphql/path");

Connect to an OAuth2 protected server

You'll find all the info on the OAuth2 client page

Change the generated code (custom templates)

The generated code is created from Velocity templates. You can override any of these templates, according to your needs.

You'll find the needed info on the Custom Templates page.

Questions about GraphQL request execution

What's the difference between GraphQL variables and bind parameter?

GraphQL Variables are defined in the GraphQL spec:

• They are a GraphQL standard
• They respect strict syntactic rules
• They can be used only in Full Request, as they must be declared before used (with the exact GraphQL type)
• They can map a full field argument. For instance: "mutation creation($human:HumanInput!){createHuman(human:$human){...}}
• They can map just part of a field argument. For instance: "mutation creation($name:String!){createHuman(human:{name:$name, ...}){...}}
• Technically :
  • The GraphQL request is sent as is (with the '$human' or '$name' in it, in the previous samples).
  • The Graphql variable value is sent in the json variables field
  • The variable content is resolved on server side

Bind parameters are proper to this plugin:

• They are not a GraphQL standard
• They are easier to use (you don't have to declare them first)
• They can be used in both Full Requests and Partial Requests, as you don't have to declare them first
• They can be mandatory (if starting with '&') or optional (if starting with '?')
  • If no value is provided at request execution time for a mandatory bind parameter, a GraphQLRequestExecutionException exception is thrown
  • If no value is provided at request execution time for an optional bind parameter, then this parameter is not sent to the GraphQL server
• They must map a full field argument.
  • For instance, this full query is valid "mutation {createHuman(human:&human){...}}
  • For instance, this full query is not valid "mutation {createHuman(human:{name:&name, ...}){...}}
• Technically :
  • The bind parameters are replaced on client side by their value, before the GraphQL request is sent to the server
• A bind parameter value may not contain GraphQL variable in its field values.

HowTo retrieve the extensions GraphQL response field?

This field is an optional field, described in the GraphQL spec. It contains a Map, and the values for this map is free, and may be anything, as choosed by the GraphQL server implementation.

To retrieve its value, you can do, for instance:

@Component
class AClass {
	
	@Autowired
	MyQueryTypeExecutor myQuery;
		
	public void doSomething() {
		// Retrieve the result as a full query
		MyQueryType resp = myQuery.exec("{directiveOnQuery}"); 
		
		// You can then retrieve the whole extensions field as a map
		Map<String, JsonNode> map = resp.getExtensionsAsMap();
		
		// Or retrieve just a value, from a key. This uses Jackson to deserialize 
		// the jsonNode into the target class for this key
		YouClass value = resp.getExtensionsField("YourKey", YourClass.class);
		
		... Do something useful
	}
}

How to execute a query/mutation which returns a scalar?

For Full requests, the request is the same as in graphiql:

@Component
public class YourClass {

	@Autowired
	QueryTypeExecutor queryExecutor;

	GraphQLRequest request;
	
	@PostConstruct
	public void init() {
		//From the Forum sample: nbBoards is a query that returns an Int, and has no arguments
		request = queryExecutor.getTopicsGraphQLRequest("query {nbBoards}");
	}
	
	int nbBoards() {
		return request.execQuery().getNbBoards();
	}
}

For Partial Requests, just give an empty response field list:

@Component
public class YourClass {

	@Autowired
	QueryTypeExecutor queryExecutor;

	GraphQLRequest request;
	
	@PostConstruct
	public void init() {
		//From the Forum sample: nbBoards is a query that returns an Int, and has no arguments
		request = queryExecutor.getNbBoardsGraphQLRequest("");
	}
	
	int nbBoards() {
		return queryExecutor.nbBoards(request);
	}
}

How to execute a request with all parameters set in the String request?

If you provide a full string, that contains all the parameters, you can do this:

public class MyClass {

	@Autowired
	AnotherMutationTypeExecutor mutationType;
	
	public void myMethod() {
		GraphQLRequest graphQLRequest = new GraphQLRequest(//
				"mutation {createHuman (human:  {name: \\\"a name with a string that contains a \\\\\\\", two { { and a } \\\", friends: [], appearsIn: [JEDI,NEWHOPE]} )"
						+ "@testDirective(value:?value, anotherValue:?anotherValue, "
						+ "anArray  : [  \\\"a string that contains [ [ and ] that should be ignored\\\" ,  \\\"another string\\\" ] , \r\n"
						+ "anObject:{    name: \\\"a name\\\" , appearsIn:[],friends : [{name:\\\"subname\\\",appearsIn:[],type:\\\"\\\"}],type:\\\"type\\\"})   "//
						+ "{id name appearsIn friends {id name}}}"//
		);

		// You can can execute the full query, without providing any parameter (as everything is set in the provided request
		Human human = mutationType.execWithBindValues(graphQLRequest, null).getCreateHuman();
	}
}