gql

A Ruby implementation of Facebook's yet-to-be-released GraphQL specification.

Visit the live demo. The source code for it can be found in the example directory.

Disclaimer: I can only speculate about how the final spec will look like. The implementation provided here is merely my guessing based on this talk and this gist. Nonetheless, this project represents how I wish the official specification will define things.

Installation

Add this line to your application's Gemfile:

gem 'gql'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gql

Usage

Usage instructions and documentation will be added when Facebook releases the official GraphQL specification.

Until then, if you have questions or comments, open a ticket in GitHub's issues tracker for this project.

In order to see how things are done and to explore this gem's features, I encourage you to study the code and tests.

Example

Apart from the more full-fledged live demo linked above, there's a simpler example available in test/fixtures/example.rb.

To play around with it, run bin/console from the project root. This starts an interactive prompt loaded with the example's models/data.

In the prompt, copy and paste the following Ruby code to execute your first query:

puts query(<<-QUERY_STRING).to_json
  user(<token>) {
    id,
    is_admin,
    full_name as name,
    created_at { year, month } as created_year_and_month,
    created_at.format("long") as created,
    account {
      bank_name,
      iban,
      saldo as saldo_string,
      saldo {
        currency,
        cents   /* silly block comment */
      }
    },
    albums.first(2) {
      count,
      edges {
        cursor,
        node {
          artist,
          title,
          songs.first(2) {
            edges {
              id,
              title.upcase as upcased_title,
              title.upcase.length as upcased_title_length
            }
          }
        }
      }
    }
  }

  <token> = "ma"  // a variable
QUERY_STRING

It all goes well, this should result in the following JSON (after prettyfication):

{
  "id": "ma",
  "is_admin": true,
  "name": "Martin Andert",
  "created_year_and_month": {
    "year": 2010,
    "month": 3
  },
  "created": "March 05, 2010 20:14",
  "account": {
    "bank_name": "Foo Bank",
    "iban": "987654321",
    "saldo_string": "100000.00 EUR",
    "saldo": {
      "currency": "EUR",
      "cents": 10000000
    }
  },
  "albums": {
    "count": 2,
    "edges": [
      {
        "cursor": 1,
        "node": {
          "artist": "Metallica",
          "title": "Black Album",
          "songs": {
            "edges": [
              {
                "id": 1,
                "upcased_title": "ENTER SANDMAN",
                "upcased_title_length": 13
              }, {
                "id": 2,
                "upcased_title": "SAD BUT TRUE",
                "upcased_title_length": 12
              }
            ]
          }
        }
      }, {
        "cursor": 2,
        "node": {
          "artist": "Nirvana",
          "title": "Nevermind",
          "songs": {
            "edges": [
              {
                "id": 5,
                "upcased_title": "SMELLS LIKE TEEN SPIRIT",
                "upcased_title_length": 23
              }, {
                "id": 6,
                "upcased_title": "COME AS YOU ARE",
                "upcased_title_length": 15
              }
            ]
          }
        }
      }
    ]
  }
}

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

Contributing

1. Fork it ( https://github.com/martinandert/gql/fork )
2. Run bin/setup to install dependencies.
3. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate: bin/rake test.
4. Create your feature branch (git checkout -b my-new-feature)
5. Add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or are fixing a bug, we need a test!
6. Make the test pass.
7. Commit your changes (git commit -am 'add some feature')
8. Push to your fork (git push origin my-new-feature)
9. Create a new Pull Request

Note

For an alternative Ruby implementation, check out rmosolgo's graphql-ruby.

The initial work on my gem was inspired by his code. Since then, both repos have diverged significantly.

License

Released under The MIT License.