Monitor and Control Simulations through GraphQL
A simulation in Alchemist can be monitored and controlled by a set of GraphQL APIs which provide a standard and flexible way to query the system.
In the following guide, you will learn how to use the API service for having a simple overview of the running simulation thanks to the playground GraphiQL with the ability to control the simulation, or to develop an Alchemist sub-module that uses the API service.
Using GraphQL service inside Alchemist
In order to attach the GraphQL API service to a simulation, you must specify
the GraphQLSimulationLauncher
in the simulation’s YAML file, providing the
server’s host and port (if not specified, default URL is: 127.0.0.1:8081
) as
shown in the following example:
launcher:
type: GraphQLServerLauncher
parameters:
host: <my-custom-host>
port: <my-custom-port>
Once the YAML file is ready, the simulation can be started as usual.
Note: At the current state, only one simulation at a time can be launched through the GraphQL simulation launcher.
Simulation’s overview in the Web Browser
Once the simulation is up and running, you can visit on your local web browser
the URL: http://<my-custom-host>:<my-custom-port>/graphiql
. In this GraphiQL
playground you will be able to lookup all the operations and types structure
that are defined in the GraphQL schema, thanks to the documentation on the
sidebar, or execute operations defining the structure of the data that you will
need.
Using GraphQL APIs inside the JVM
If you plan to use GraphQL APIs for the development of a module inside
Alchemist, you can do so by using the provided GraphQLClient
. This class will
take care of establishing a connection to the GraphQL server, validate and
compute operations and give back their results. This component has been
developed in a multiplatform environment, so that applications can lay on
platforms like Android, iOS, Kotlin/JS or Kotlin/Native.
In order to use the GraphQL API service, refer to the following steps:
-
Include the
alchemist-graphql
common source set in your project. -
Define the structure of the data you need when executing one of the provided operations, inside a set of files with
.graphql
extension placed in thealchemist-graphql/src/commonMain/resources/graphql/
directory.
# NodeQuery.graphql
query Node($id: Int!) {
nodeById(id: $id) {
contents {
entries {
molecule {
name
}
concentration
}
}
}
}
You can test the structure of the data that you need inside the GraphiQL playground, in order to get predicable results when compiling your operations. GraphiQL also notices you if you are writing incorrect operations with useful explanation about the errors.
-
Run the Gradle task
./gradlew :alchemist-graphql:generateAlchemist-graphqlApolloSources
in order to generate Kotlin’s source code that represents the results of operations called in previously defined files. -
Use the defined GraphQL compiled operations on top of the
GraphQLClient
to execute them.
val client: GraphQLClient = GraphQLClientFactory.basicClient()
/* `NodeQuery` is the generated code for the
GraphQL operation defined in the example above */
val node: Node? = client.query(NodeQuery(nodeId = 10)).execute().data