How Integration Server Generates GraphQL Descriptor and Supporting Assets
When you import a GraphQL schema in Integration Server then Integration Server creates these assets.
1. A GraphQL descriptor with the name as provided by user.
For example, consider the following schema.
Schema :
type Query {
getLink: Link
}
type Link {
id: ID
url: String
}
When you create a GraphQL descriptor using the above GraphQL schema with name graphqlSample, then Designer appears like this:
In the above GraphQL descriptor, there are three tabs, Operations, Schema, and Comments.
Working with Operations Tab
Under the Operations tab, you can view all the operations with their fields listed. For the above schema, Query operation is listed with field getLink. Each field has two children, Input and Output. The Input document contains three fields query, variables, and operationName. These three fields represent three input parameters, query, variables, and operationName in the input request to query this field. The Output document contains two fields data and errors. These two fields represent the two output parameters data and errors in response to the query for this field.
The Input field:
The Output field:
In the Output field, the document data contains fields corresponding to the type of the field (in this case Link) and the error list contains the list of errors (if any) occurred while resolving the field getLink.
errors: The structure of the error document is according to the GraphQL specification.
message: This field contains error message.
description: This field contains the description about the error.
validationErrorType: If there is any error while resolving field then this field contains the type of the validation which is failed. The possible values for this field can be:
DefaultForNonNullArgument
WrongType
UnknownType
SubSelectionRequired
SubSelectionNotAllowed
InvalidSyntax
BadValueForDefaultArg
FieldUndefined
InlineFragmentTypeConditionInvalid
FragmentTypeConditionInvalid
UnknownArgument
UndefinedFragment
NonInputTypeOnVariable
UnusedFragment
MissingFieldArgument
MissingDirectiveArgument
VariableTypeMismatch
UnknownDirective
MisplacedDirective
UndefinedVariable
UnusedVariable
FragmentCycle
FieldsConflict
InvalidFragmentType
LoneAnonymousOperationViolation
NonExecutableDefinition
DuplicateOperationName
queryPath: If the input query is invalid then this field contains the path of the query that contains the error.
underlyingErrors: If there are any underlying errors while resolving field then this field contains those errors.
errorType: This field contains the name of the error type. For example, if there is any validation error while resolving any field then this filed contains the value under
ValidationError.
path: If any error can be associated to a particular field in the GraphQL result, then this field contains the path of the response field that experienced the error.
extensions: If there are any additional error information then it can be added in this field.
locations: If error can be associated to a particular point in the requested GraphQL document, then this field contains the locations details.
Working with Schema Tab
The Schema tab contains the read only GraphQL schema that was used to create the GraphQL descriptor.
2. A folder with name <GRAPHQL_DESCRIPTOR>_ at the same level of GraphQL descriptor.
For example, if you create a GraphQL descriptor with name graphqlSample then a GraphQL descriptor and a folder graphqlSample_ is created as below:
3. Folders with name types and resolvers under <GRAPHQL_DESCRIPTOR>_ folder. All the document types are created under the types folder and all the resolver services are created under the resolvers folder.
4. Integration Server creates resolver services for all the root Queries and Mutations under their respective operations folder.
For example, consider the following schema:
Schema:
type Query {
getX: Int
getY: Int
}
type Mutation {
setX(x: Int): Int
setY(y: Int): Int
}
If you import the above schema in Integration Server with name graphqlSample, then Integration Server creates the resolver services for Query operation under graphqlSample_/resolvers/Query folder, and the resolver services for Mutation operation under graphqlSample_/resolvers/Mutation folder.
The operation logic to resolve the field can be added to generate the resolver services.
Note: The input and output signatures for the generated resolver services are read only, and must not be changed. If the signatures are changed then the resolver services might not work properly.
5. For the GraphQL types, the document types Object, Interface, Union and Input are generated under types folder.
For example, consider the following schema:
Schema:
type Query {
getUser(in: UserInput) : User
}
interface User {
id: ID
}
type Employee implements User {
id: ID
name: String
}
type Photo {
x: Int
}
type Friend {
y: String
}
union PhotoOrFriend = Photo | Friend
input UserInput {
id: ID
}
If you import the above schema in Integration Server with name graphqlSample then Integration Server generates the document types, User, Employee, Photo, Friend, PhotoOrFriend, and UserInput inside types folder.
The document type has same fields that exist in the GraphQL type. For example, Employee type has two fields id and name, hence the document type Employee contains same fields.
The document type for Union contains all the fields from all the available types. For example, in the above schema the Union type PhotoOrFriend can return an Object of type Photo or Friend. The type Photo has a field x and the type Friend has a field y so the document type for PhotoOrFriend contains both the fields x and y.
Note: The generated document types are read only. The fields in the document types must not be changed. If the fields are changed then the GraphQL descriptor might not work properly.
6. If the field is of Scalar type or Enum type and has no arguments, then Integration Server does not generate any resolver service for that field. For example, in the above schema Employee type has fields id and name of Scalar types, so Integration Server does not generate any resolver service for these fields.
7. If a GraphQL type has a field of type Object or Interface or Union, or the field has input argument then Integration Server generates a resolver service for the field with name <FIELD_NAME>Resolver, under the folder <GRAPHQL_DESCRIPTOR>_/resolvers/<TYPE>/<FIELD_NAME>Resolver.
For example, consider the following schema:
Schema:
type Query {
getLink(id: ID): Link
}
type Link {
id: ID
postedBy: User
}
type User {
id: ID
name: String
dept(id: ID): String
}
If you import the above schema with name graphqlSample. Here, Link object has a field which is of object type User, so Integration Server generates a resolver service postedByResolver under graphqlSample_/resolvers/Link folder. User type has field dept with input argument, so Integration Server generates a resolver service deptResolver under graphqlSample_/resolvers/User folder.
