A swift component with a DSL to declare GraphQL queries and to get string representations out of them

apps-team, dsl, graphql, graphql-query, swift



A swift component with a DSL to declare GraphQL queries and to get string representations out of them.
Written for iOS 8+, WatchOS 2, tvOS and Mac OS X apps.

CI Status License Platform swift2 Carthage compatible Version




GraphQLicious supports Carthage. To install it, simply add the following line to your Cartfile

github "WeltN24/GraphQLicious"


GraphQLicious is available through CocoaPods. To install it, simply add the following line to your Podfile

pod "GraphQLicious"


If you don't use CocoaPods, you can still add GraphQLicious as a submodule, drag and drop GraphQLicious.xcodeproj into your project, and embed GraphQLicious.framework in your target.

  • Drag GraphQLicious.xcodeproj to your project
  • Select your app target
  • Click the + button on the Embedded binaries section
  • Add GraphQLicious.framework


You can directly drag and drop the needed files into your project, but keep in mind that this way you won't be able to automatically get all the latest features.
The files are contained in the Sources folder and work for the iOS framework



Let's assume, we have the id of an article and we want to have the headline, body text and opener image of that article.

Our graphQL query for that will look like this:

query {
    test: content(id: 153082687){
fragment contentFields on Content {
    image(role: "opener", enum: [this, that]){
fragment imageContent on Image {
fragment urlFragment on Image {
     url (ratio: 1, size: 200) 

First, let's create a Fragment to fetch the contents of an image, namely the image id and the image url

let imageContent = Fragment(
    withAlias: "imageContent",
    name: "Image",
    fields: [

Next, let's embed the Fragment into a Request that gets the opener image.
Note: Argument values that are of type String, are automatically represented with quotes.
GraphQL also gives us the possibility to have custom enums as argument values. All you have to do, is letting your enum implement ArgumentValue and you're good to go.

enum customEnum: String, ArgumentValue {
  case This = "this"
  case That = "that"

  private var asGraphQLArgument: String {
    return rawValue // without quotes

let customEnumArgument = Argument(
  key: "enum",
  values: [
let imageContentRequest = ReadingRequest(
    name: "image",
    arguments: [
        Argument(key: "role", value: "opener"),
    fields: [

So now we have a Request with an embedded Fragment. Let's go one step further.
If we want to, we can imbed that Request into another Fragment. (We can also embed Fragments into Fragments)
Additionally to the opener image with its id and url we also want the headline and body text of the article.

let articleContent = Fragment(
    withAlias: "contentFields",
    name: "Content",
    fields: [

Finally, we put everything together as a Query. A Query always has a top level Request to get everything started, and requires all the Fragments that are used inside.

let query = Query(readingRequest: ReadingRequest(
    withAlias: "test",
    name: "content",
    arguments: [
        Argument(key: "id", values: [153082687])
    fields: [
    fragments: [articleContent, imageContent]

All we have to do now is to call create() on our Query and we're good to go.



Let's assume, we want to change our username and our age in our backend and we want to have the new name and age back to make sure everything went right.

Let's assume further, our server provides a mutating method editMe for exactly that purpose.

Our graphQL query for that will look like this:

mutation myMutation {
    editMe(input: {
        name: "joe",
        age: 99

Let us first create the actual mutating function. We can use a MutatingRequest for that. As Argument values we give information about which fields should be changed and what's the actual change

let mutatingRequest = MutatingRequest(
      mutationName: "editMe",
        key: "input",
        mutatingValue: MutatingValue(
          withFields: [
            MutatingField(name: "name", value: "joe"),
            MutatingField(name: "age", value: 99)
      responseFields: [

Finally, we put everything together as a Mutation.

Mutations work just like Queries

let mutation = Mutation(
    withAlias: "myMutation",
    mutatingRequest: mutatingRequest

After we've done that we can create the request.



GraphQLicious was made in-house by WeltN24


Felix Dietz,, @joemcbomb on Github, @joemcbomb on Twitter

Vittorio Monaco,, @vittoriom on Github, @Vittorio_Monaco on Twitter


GraphQLicious is available under the MIT license. See the LICENSE files for more info.