Kraph 
In short, this is a GraphQL request JSON body builder for Kotlin. It will generate the JSON string for request body that work with GraphQL Server. For example, we have this GraphQL query to list all notes:
query {
notes {
id
createdDate
content
author {
name
avatarUrl(size: 100)
}
}
}
Which is written in Kotlin using Kraph like this:
Kraph {
query {
fieldObject("notes") {
field("id")
field("createdDate")
field("content")
fieldObject("author") {
field("name")
field("avatarUrl", mapOf("size" to 100))
}
}
}
}
As you can see, we can achieve our goal with just a few tweaks from the original query.
NOTE: Kraph is still in an early stage. The usage may change in further development.
Features
- DSL builder style. Make it easier to read and use.
- Support Cursor Connection and Input Object Mutation in Relay.
Set up
Adding Kraph to build.gradle
repositories {
jcenter()
}
dependencies {
compile "me.lazmaid.kraph:kraph:x.y.z"
}
Guide
If you are not familiar with GraphQL syntax, it is recommended to read the GraphQL introduction for an overview of how Graphql works. Usually, you should be able to use queries from other tools (e.g. GraphiQL) with a few tweaks. First, let's see what Kraph provides for you.
Simple GraphQL
-
queryandmutationrepresents the Query and Mutation operations of GraphQL. The name of the query or mutaton can be passed as a string.GraphQL:
query GetUsers { ... }
Kraph:
Kraph { query("GetUsers") { ... } }
GraphQL:
mutation UpdateUserProfile { ... }
Kraph:
Kraph { mutation("UpdateUserProfile") { ... } }
-
fieldandfieldObjectrepresent accessors for fields. Though there are technically no differences,fieldObjectmay be chosen for clarity to indicate that a field must contain another set of nested fields as an argument. Both of them take aMap<String, Any>that maps Kotlin data types to the GraphQL data types for input objects. You can also specify an alias usingaliasto change the name of the returned field.query { users { nick: name email avatarUrl(size: 100) } }
Kraph { query { fieldObject("users") { field("name", alias = "nick") field("email") field("avatarUrl", args = mapOf("size" to 100)) } } }
-
fragmentprovides a mechanism for creating GraphQL Fragments. To use a fragment in a query requires two steps. The first is to define the fragment, letting Kraph know how to handle it later:fragment UserFragment on User { name email avatarUrl(size: 100) }
Kraph.defineFragment("UserFragment") { field("name") field("email") field("avatarUrl", mapOf("size" to 100)) }
Then, when you are creating your query, you can simply use the fragment and its fields will be expanded:
query { users { ...UserFragment } }
-
fragmentprovides a mechanism for creating GraphQL Fragments. To use a fragment in a query requires two steps. The first is to define the fragment, letting Kraph know how to handle it later:fragment UserFragment on User { name email avatarUrl(size: 100) }
Kraph.defineFragment("UserFragment") { field("name") field("email") field("avatarUrl", mapOf("size" to 100)) }
Then, when you are creating your query, you can simply use the fragment and its fields will be expanded:
query { users { ...UserFragment } }
Kraph { query("GetUsers") { fieldObject("users") { fragment("UserFragment") } } }
Relay
funcrepresents a Field inside a Mutation block that follows the Relay Input Object Mutations specification.mutation { userLogin(input: {email: "[email protected]", password: "abcd1234"}) { accessToken user { id email } } }
Kraph { mutation { func("userLogin", input = mapOf("email" to "[email protected]", "password" to "abcd1234")) { field("accessToken") fieldObject("user") { field("id") field("email") } } } }
cursorConnectionrepresents a Field that follows the Relay Cursor Connections specificationquery { users(first: 10, after: "user::1234") { edges { node { id name } } } }
Kraph { cursorConnection("users", first = 10, after = "user::1234") { edges { node { field("id") field("name") } } } }
Request/Query String
toRequestString()will generate a JSON body to send in POST request.toGraphQueryString()will give you the formatted GraphQL string. This is very useful for debugging.val query = Kraph { query { fieldObject("users") { field("name") field("email") field("avatarUrl", args = mapOf("size" to 100)) } } } println(query.toRequestString()) /* * Result: * {"query": "query {\nnotes {\nid\ncreatedDate\ncontent\nauthor {\nname\navatarUrl(size: 100)\n}\n}\n}", "variables": null, "operationName": null} */ println(query.toGraphQueryString()) /* * Result: * query { * notes { * id * createdDate * content * author { * name * avatarUrl(size: 100) * } * } * } */
requestQueryString(),requestVariableString()andrequestOperationName()provide more fine grained access to the components of the full request string, which are sometimes necessary depending on your HTTP request builder and GraphQL server setup. They provide the values for thequery,variables, andoperationNameparameters, respectively, and so are good for creating GET requests. Please note thatrequestVariableString()will always returnnulluntil variable support is implemented.
Contributing to Kraph
We use Github issues for tracking bugs and requests. Any feedback and/or PRs is welcome.
18 Dec 2, 2022
1 Feb 2, 2022
52 Dec 30, 2022
0 Dec 28, 2021
7 Sep 17, 2022
0 Feb 12, 2022
255 Jan 3, 2023
5 Nov 4, 2022
0 Oct 31, 2021
5 Mar 20, 2022
2.5k Jan 9, 2023
1 Nov 27, 2021
5 Oct 4, 2022
1 Feb 13, 2022
15 Oct 21, 2022
1 May 17, 2022
2 Sep 17, 2022
4 Jan 12, 2022
1 Jan 17, 2022