9. Write your first mutation

In this section, you will write your first mutation to log in to the backend.

A mutation is used to change data on your server. Here the login mutation will create a session based on your email address.

Prototype your mutation in Sandbox Explorer

Open your Sandbox Explorer and click on the plus symbol to add a new tab. Next, click on the Schema icon to get back to looking at your schema, and select "Mutation" to look at your list of mutations:

Scroll down to take a look at the login mutation:

Click the play button to the right to open that mutation in the Explorer tab. When it opens, click the plus sign to add the operation:

Notice the red error indication - this is because the type returned by the mutation is User, which is not a leaf type: you need to choose which of the user's fields the mutation will return. For our purposes, we only need the token field, so add it by clicking the plus sign next to it.

You'll also notice that email wasn't automatically added as an argument even though it doesn't seem to have a default value: that's because email is of type String - which remember, in GraphQL, means that it's not required (although obviously you won't get too far without it).

Click the plus sign next to the email argument to have that argument added:

You'll also notice that Sandbox Explorer has added a variable to your "Variables" section to match the login email.

Click the Submit Operation button your mutation. You'll see that since you sent null for the email address, you get back null for the login:

Now, replace null in the Query Variables section with an actual email address:

1
{ "email": "me@example.com" }

Press the Submit Operation button, and this time you'll get an actual response:

Next, copy the operation, either manually or using the three-dot menu's "Copy operation" option.

Add the mutation to the project

Now that your mutation is working, add it to your project. Create a file named Login.graphql next to schema.graphqls and your other GraphQL files and paste the contents of the mutation:

1
mutation Login($email: String!) {
2
  login(email: $email) {
3
    token
4
  }
5
}

Note: we've also marked the email variable as non-nullable by adding ! to the end of the type, since we always want to pass a value for it.

Build your project to generate the LoginMutation class.

Connect the Submit button to your mutation

Open LoginFragment.kt and like you did for the other fragments, override onViewCreated. Add a click listener and some checks to verify that the email is a valid email:

1
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
2
        super.onViewCreated(view, savedInstanceState)
3

4
        binding.submitProgressBar.visibility = View.GONE
5
        binding.submit.setOnClickListener {
6
            val email = binding.email.text.toString()
7
            if (!Patterns.EMAIL_ADDRESS.matcher(email).matches()) {
8
                binding.emailLayout.error = getString(R.string.invalid_email)
9
                return@setOnClickListener
10
            }
11

12
            // TODO: More code here
13
        }
14
    }

From the click listener, display the ProgressBar and execute the query with the email the user just entered. Replace the TODO with:

1
binding.submitProgressBar.visibility = View.VISIBLE
2
            binding.submit.visibility = View.GONE
3
            lifecycleScope.launchWhenResumed {
4
                val response = try {
5
                    apolloClient.mutation(LoginMutation(email = email)).execute()
6
                } catch (e: Exception) {
7
                    null
8
                }
9

10
                // TODO: handle errors
11
            }

Handle errors if needed by replacing the TODO you just added:

1
val token = response?.data?.login?.token
2
                if (token == null || response.hasErrors()) {
3
                    binding.submitProgressBar.visibility = View.GONE
4
                    binding.submit.visibility = View.VISIBLE
5
                    return@launchWhenResumed
6
                }

Finally if everything is successful, store the token and go back to the previous screen at the end of launchWhenResumed:

1
User.setToken(requireContext(), token)
2
                findNavController().popBackStack()

User is a helper class that saves the token in EncryptedSharedPreference. This is the reason why this tutorial uses API level 23+. Apollo Kotlin itself supports API levels 21+.

Test the login

Go to the details fragment, click Book and in the Login fragment, enter your email and click Submit. You now have a token that allows you to authenticate your operations.

In the next section, you will use authenticated operations to book a flight.