Initial setup GraphQL using graphql-ruby 1.8

- All definitions have been replaced by classes:
  http://graphql-ruby.org/schema/class_based_api.html
- Authorization & Presentation have been refactored to work in the
  class based system
- Loaders have been replaced by resolvers
- Times are now coersed as ISO 8601

1 files changed, 21 insertions, 13 deletions

diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md
index 78e634df347..dcd5377284c 100644
--- a/doc/api/graphql/index.md
+++ b/doc/api/graphql/index.md
@@ -2,33 +2,41 @@
 
 > [Introduced][ce-19008] in GitLab 11.0.
 
-## Enabling the GraphQL feature
+[GraphQL](https://graphql.org/) is a query language for APIs that
+allows clients to request exactly the data they need, making it
+possible to get all required data in a limited number of requests.
 
-The GraphQL API itself is currently in Beta, and therefore hidden behind a
-feature flag. To enable it on your selfhosted instance, run
-`Feature.enable(:graphql)`.
+The GraphQL data (fields) can be described in the form of types,
+allowing clients to use [clientside GraphQL
+libraries](https://graphql.org/code/#graphql-clients) to consume the
+API and avoid manual parsing.
 
-Start the console by running
+Since there's no fixed endpoints and datamodel, new abilities can be
+added to the API without creating breaking changes. This allows us to
+have a versionless API as described in [the GraphQL
+documentation](https://graphql.org/learn/best-practices/#versioning).
 
-```bash
-sudo gitlab-rails console
-```
+## Enabling the GraphQL feature
+
+The GraphQL API itself is currently in Alpha, and therefore hidden behind a
+feature flag. You can enable the feature using the [features api][features-api] on a self-hosted instance.
 
-Then enable the feature by running
+For example:
 
-```ruby
-Feature.enable(:graphql)
+```shell
+curl --data "value=100" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/graphql
 ```
 
 ## Available queries
 
-A first iteration of a GraphQL API inlcudes only 2 queries: `project` and
+A first iteration of a GraphQL API includes only 2 queries: `project` and
 `merge_request` and only returns scalar fields, or fields of the type `Project`
 or `MergeRequest`.
 
 ## GraphiQL
 
 The API can be explored by using the GraphiQL IDE, it is available on your
-instance on `gitlab.example.com/api/graphiql`.
+instance on `gitlab.example.com/-/graphql-explorer`.
 
 [ce-19008]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19008
+[features-api]: ../features.md