Ktor and GraphQL: Getting Started

Writing Data with Mutations

In REST, any requests made may cause side-effects on the server. But by convention, it’s recommended to not use GET requests to modify data. GraphQL is similar — any query should not do a data write. However, it’s useful to establish a convention that any operations that cause a write operation should be sent via a mutation.

You’ll first add a mutation to allow creating new players. Add a createPlayer mutation to the SchemaBuilder.schemaValue() function:

 // 1
  mutation("createPlayer") {
    // 2
    description = "Create a new player"
    // 3
    resolver { playerInput: PlayerInput ->
      try {
        // 4
        val uid = java.util.UUID.randomUUID().toString()
        val player = Player(uid, playerInput.name, playerInput.team, playerInput.position)
        repository.createPlayer(player)
        true
      } catch (e: Exception) {
        false
      }
    }
  }

The above code breaks down as follows:

1. Create a mutation with a unique name.
2. Give the method a description to help developers better understand the method.
3. Use a resolver accepting a PlayerInput. Recall that you defined this class earlier with the schema, so it can be used a typed input.
4. Create the Player object, and store it in the list.

As with queries, you’ll call the respective repository methods for each resolver that you create. In this case, that means actions that’ll affect the result of the data. After implementing the code above and re-running the project again, you’ll see this:

In order to test the createPlayer mutation, replace the query with:

mutation createNewPlayer($playerInput: PlayerInput!){
  createPlayer(playerInput:$playerInput)
}

Inside the Query variables, put the following code that represents the object in the argument field:

{
  "playerInput": {
    "name": "Test player",
    "position": "DEF",
    "team": "Barcelona"
  }
}

When you execute this, expect the following result from the playground:

Congratulations! You’ve successfully created a GraphQL API! If you want to challenge yourself, try to query your API to retrieve the list of players after creating a new one. Similarly, checkout the completed project for implementations of deletePlayer and updatePlayer to see how to delete and update a player respectively.

Where to Go From Here?

You can download the completed project files by clicking the Download Materials button at the top or bottom of the tutorial.

You’ve just learned how to create a GraphQL application using Ktor and KGraphQL! Although you’ve scratched the surface, there are many areas of either Ktor, or KGraphQL you might want to explore.

• Understand how to pass Context to each request.
• How to add server-side authorization and authentication.
• How to deploy your Ktor application.
• To learn more about GraphQL, go to: https://graphql.org/

We hope you enjoyed this tutorial. If you have any questions, please join the discussion below.