Usage Notes for GraphQL Descriptors

If a field of type list and the dimensions are greater than or equal to 2, then that field is represented as an object array in Integration Server.

Consider the following schema:

Schema:
type Query {
getPrices: [[int]]
}

After importing this schema in Integration Server, the field getPrices is represented as below:

Integration Server ignores the duplicate member entry for Union type. For example, if a Union is defined like this:

union Result = Author | Author

Then Integration Server does not throw any error and ignores the second entry of the Author object in Union definition.

An Input type extension cannot re-define a field from the original Input type.

input In {
name: String
}
extend input In {
name: Int
}

Here, the extension re-defines the field name as Int and is not allowed. However, you can define as follows:

input In {
name: String
}

extend input In {
name: String
}

Same point is applicable for Object and Interface types as well.

If duplicate fragments exist in the Query then Integration Server ignores all other fragments and considers the last fragment. For example, the following query:

{
dog {
...fragmentOne
}
}

fragment fragmentOne on Dog {
name
}

fragment fragmentOne on Dog {
owner {
name
}
}

Here, fragmentOne is defined twice in the query so Integration Server does not throw any error but it returns the result for the last fragment.

fragment fragmentOne on Dog {
owner {
name
}
}

While forming a query there is a difference between assigning values to arguments or fields and passing as Query variables. For example, for the following schema:

Schema:
type Query {
getUser(id: Int):User
}

type User {
id: Int
name: String
}

While querying the field getUser, you can send the value for input argument id in Query variables or set in the query directly. Consider the following query:

query getUserQuery($id: Int) {
getUser(id: $id) {
id
name
}
}

Assigning the input argument value in Query variables:

{
"id": "100"
}

Here, for an Int argument id, a string value is passed through the Query variables, but as the value "100" can be coerced to Int so Integration Server does not throw any error. Integration Server throws error only when coercion is not possible.

Assigning the input argument value in query:

query getUserQuery {
getUser(id: "100") {
id
name
}
}

Here, a value "100" is assigned to argument id, which can be coerced to Int but still the query execution fails while assigning values to the arguments in the query because the value is not of exact type.

The following are the coercion rules:

For Boolean fields, if a String value is passed then true(case insensitive) is coerced to true, and all other values are coerced to false.

For Boolean fields, if a numeric value is passed then all non-zero numbers are coerced to true and zero is coerced to false.

For all the String fields, if a non String value is passed then it is coerced to String representation of that value. Integration Server calls toString() on the passed value.

For all the Numeric(Int, Short, Long, Float, BigInteger, BigDecimal) fields, if the value is coerced to the specific type then the value is coerced otherwise Integration Server throws an error.

For all the Char fields, the String value of length is coerced to Char. Integration Server throws an error if any other value is passed.

If duplicate arguments are passed in the query then Integration Server considers the last argument and ignores all the previous occurrences of that argument. Consider the following example,

query getUserQuery {
getUser(id: 100, id: 200,id: 300) {
id
name
}
}

Here, Integration Server considers the last value for id (300) and ignores all the previous values.

The fields in the generated document types and the input or output signatures of the generated resolver services are non-editable. If you edit any of these values then GraphQL descriptor might not work as expected.

Do not create the custom services or folders, inside the folders created for GraphQL descriptor (<DESCRIPTOR>_{resolvers}{types}{types}/<TYPE>). While refreshing the GraphQL descriptor Integration Server removes the custom folder or services.

If parent resolver returns null value then Integration Server does not invoke the child resolver.

For example, consider the following schema:

schema:
type Query {
queryUser: User
}

type User {
adreess: Address
}

type Address {
line1: String
line2: String
}

Here, when the graphql descriptor is invoked using this query:

query {
queryUser {
adreess {
line1
line2
}
}
}

Initially, Integration Server invokes the root resolver service queryUserResolver to resolve the field queryUser, now you have only one field of type object so again Integration Server invokes addressResolver resolver service to resolve the address field. Here, Integration Server does not populate any data because User does not have any leaf fields (Scalar or Enum fields) but still queryUserResolver needs to return an empty document for queryUser field otherwise (if queryUserResolver returns null), Integration Server does not invoke addressResolver.

If the objects of a Union type member have common fields with different types, then the fields need to be set properly in the resolver otherwise Integration Server might throw an error.

Consider the following schema:

Query {
getUnion: Result
}

union Result = Photo | Person

type Photo {
x: String
}

type Person {
x: [Int]
}

When you import the above schema into Integration Server then the document type for Union result contains fields from both the types Photo and Person, but here the field names are same and the field types are different so if getUnionResolver is returning data for Photo then it has to set the String value for field x and if resolver is returning Person then it has to set Integer list value for field x. If you set both the values or set incorrect values then Integration Server throws an error.

The following special characters ? ~ ` # % ^ & * - @ + = \\ \" ; ' < > , / are not allowed as field names, types, arguments, and Enum values.

multibyte characters (such as Japanese or Chinese) are not allowed in GraphQL schema.

If a GraphQL schema contains GraphQL types with same name and in different case, or fields with same name and different case then Integration Server appends random number to the resolver service names and document type names to uniquely identify them in Integration Server namespace.

Consider the following schema:

schema:
Query {
getUser: User
getUSER: USER
}

type User{
name: String
}
type USER {
name:String
}

Here, Query type has two fields getUser and getUSER with same name but different case, and there are two types User and USER with same name but different case, so when you import this schema in Integration Server, Integration Server generates the resolver services and the document types as below:

Here, Integration Server appends a number, 1 in resolver name for getUSER field, getUSER1Resolver and also appends a number, 1 in document type name for User.