The following is the first few sections of a chapter from GraphQL and Android, plus headings for the remaining major sections, to give you an idea about the content of the chapter.


Miscellaneous GraphQL Syntax

Many programming and data-access languages have bits and pieces, or odds and sods, of miscellaneous syntax that are important, yet not important enough to warrant their own chapter in a book.

This chapter covers some of that syntax, with respect to GraphQL.

Arguments on Nested Fields

Back in the chapter on variables and arguments, we saw how root fields can take arguments, to make it easier to pass in details that may vary by invocation:

query find($search: String!) {
  findTrip(searchFor: $search) {
    id
    title
    startTime
    priority
    duration
  }
}

Here, the argument is applied to one of the root query fields, findTrip. This feels fairly typical and a bit reminiscent of passing parameter values to Java methods.

However, fields other than root fields might also accept arguments. These can have the same sorts of roles as do arguments on root fields: sort order, pagination, etc. Here are some other scenarios where arguments on nested fields may prove useful.

Scenario: Conversion

Sometimes, the argument might be for simple things like format or unit conversion:

query find($search: String!) {
  findTrip(searchFor: $search) {
    id
    title
    startTime
    priority
    duration(timeUnit: DAYS)
  }
}

Here, a (theoretical) revised version of our server takes a timeUnit argument on duration, from some (theoretical) enum where one of the values is DAYS. This would be akin to using TimeUnit.DAYS in Java date/time conversions.

Typically — though not universally — fields in this scenario will have a default value for the argument. That way, you can either include the argument or skip it, as you see fit. If you skip the argument, some default format or unit will be used (e.g., minutes in the case of duration).

Scenario: Filtering

Sometimes, the argument might be for restricting the data to some subset:

query find($search: String!) {
  findTrip(searchFor: $search) {
    id
    title
    startTime
    priority
    duration(timeUnit: DAYS)
    plans(type: FLIGHT) {
      id
      title
    }
  }
}

Here, another (theoretical) revised version of the server takes a type argument on plans, for some (theoretical) enum where one of the values is FLIGHT. This might be used by the server to only return those plans that are flights, not lodging stays, for clients that only care about the flights.

Once again, often times the argument will have a default value; in the case of filtering, the typical default meaning is “give me everything”.

Developing Clients Using Arguments on Nested Fields

In general, though, the fact that these arguments are nested does not really impact your development of a GraphQL client. Either the arguments are being set from variables, or they are not. Variables are still all declared on the operation itself. So, you might have more variables than before, but the fact that one or more of those variables happen to be used in nested fields’ arguments does not impact how you provide the variables’ values:

Directives

The preview of this section was last seen in the Bermuda Triangle.

Deprecations

The preview of this section is off trying to sweet-talk the Khaleesi into providing us with a dragon.