The following is the first few sections of a chapter from The Busy Coder's Guide to Android Development, plus headings for the remaining major sections, to give you an idea about the content of the chapter.


Basic Dynamic GraphQL in Android

Now, let’s see how we can start working with GraphQL from our own Android app.

Dynamic vs. Static

This chapter’s title refers to “dynamic” GraphQL. And, if you peek ahead to the next chapter, you will see that it refers to “static” GraphQL. That distinction drives the libraries and tools that we can use for making our GraphQL requests.

Dynamic

Sometimes, the GraphQL request that we want to execute is not knowable when we write our app. GraphiQL, for example, allows you to enter in arbitrary GraphQL documents and execute operations from them.

In these cases, we need some code that can take the GraphQL, along with details like the server URL, and execute requests.

Static

Sometimes, the GraphQL representing our request(s) is known when we write our app. Pieces of data that go along with the request might not be known until runtime, though. For example, we might know that we want to find a trip based on a search term, but we do not know the search term until our app’s user types one in on their device.

This is reminiscent of a SQL SELECT statement that we hard-code into our app, but some of the values to use in the WHERE clause are based on user input or other runtime values. In this case, we typically use positional parameters (e.g., SELECT * FROM foo WHERE ID=?), so our SQL SELECT statement can still be hard-coded, but where we provide the parameter values at runtime.

As we saw in a previous chapter, GraphQL offers a similar separation, where we use a separate “variables” bit of JSON for the values that might vary at runtime. This allows us to have our GraphQL document as a plain, unvarying string.

The nice thing about having a GraphQL document as an ordinary string is that if that string is in a nice location — say, a plain text file in our project — we can do more work at compile time to make it easier for us to use that GraphQL.

We will explore all of this and more in the next chapter. The key for now is:

GraphQL and HTTP

The GraphQL specification does not require any particular transport mechanism (e.g., HTTP) or particular serialization format (e.g., JSON). HTTP and JSON are common approaches, but they are not required.

Any time that you have a specification that does not specify something, you run into potential problems with multiple incompatible implementations of that “something”.

While the GraphQL specification is agnostic, the GraphQL documentation does make some recommendations for how GraphQL-over-HTTP should work.

Of note, GraphQL usually uses a single URL or “endpoint” for all requests (e.g., http://graphql-demo.commonsware.com/0.2/graphql). This is in contrast with REST, which uses URLs as part of the content identification strategy.

A GraphQL request is made up of three pieces. The big one is the GraphQL document, containing your queries and mutations, written in GraphQL syntax. This is required for all requests. The others are:

You can use either an HTTP GET or POST to make the GraphQL request. A GET will use query parameters for the document, variables, and operation name:

Element Required? Query Parameter Name Encoding
Document yes query GraphQL, URL-encoded
Operation Name sometimes operationName URL-encoded
Variables sometimes variables JSON object, URL-encoded

The operationName is required if there are 2+ operations in the document, but if the document contains only a single operation, the operationName is not required. Similarly, if the requested operation takes variables, values for those variables are required; otherwise, the variables query parameter can be skipped.

Usually, a POST will wrap those three elements in JSON and deliver that as the payload on the request, with JSON object keys matching the query parameter names:

{
  "query": "query something($var1:String!, $var2:Int) { ... } ...",
  "operationName": "something",
  "variables": { "var1": "foo", "var2": 5 }
}

The MIME type of the POST request would be application/json in this case.

The HTTP response should be in the form of a JSON object as we have seen in the GraphiQL examples so far, containing data and/or errors.

Using OkHttp for GraphQL

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

Getting a Parsed Response

The preview of this section was lost in the sofa cushions.

Can’t We Do Better Than Maps of Objects?

The preview of this section was traded for a bag of magic beans.