Merge branch 'bvl-graphql-start-34754' into 'master'

GraphQL setup: Basic Project and Merge request endpoint

Closes #34754

See merge request gitlab-org/gitlab-ce!19008

3 files changed, 125 insertions, 0 deletions

diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md
new file mode 100644
index 00000000000..dcd5377284c
--- /dev/null
+++ b/doc/api/graphql/index.md
@@ -0,0 +1,42 @@
+# GraphQL API (Beta)
+
+> [Introduced][ce-19008] in GitLab 11.0.
+
+[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 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.
+
+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).
+
+## 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.
+
+For example:
+
+```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 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/-/graphql-explorer`.
+
+[ce-19008]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19008
+[features-api]: ../features.md
diff --git a/doc/development/README.md b/doc/development/README.md
index 898c60e96c0..78c1b6bc6e3 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -32,6 +32,8 @@ description: 'Learn how to contribute to GitLab.'
 - [GitLab utilities](utilities.md)
 - [API styleguide](api_styleguide.md) Use this styleguide if you are
   contributing to the API.
+- [GrapQL API styleguide](api_graphql_styleguide.md) Use this
+  styleguide if you are contribution to the [GraphQL API](../api/graphql/index.md)
 - [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
 - [Working with Gitaly](gitaly.md)
 - [Manage feature flags](feature_flags.md)
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
new file mode 100644
index 00000000000..f74e4f0bd7e
--- /dev/null
+++ b/doc/development/api_graphql_styleguide.md
@@ -0,0 +1,81 @@
+# GraphQL API
+
+## Authentication
+
+Authentication happens through the `GraphqlController`, right now this
+uses the same authentication as the Rails application. So the session
+can be shared.
+
+It is also possible to add a `private_token` to the querystring, or
+add a `HTTP_PRIVATE_TOKEN` header.
+
+### Authorization
+
+Fields can be authorized using the same abilities used in the Rails
+app. This can be done using the `authorize` helper:
+
+```ruby
+module Types
+  class QueryType < BaseObject
+    graphql_name 'Query'
+
+    field :project, Types::ProjectType, null: true, resolver: Resolvers::ProjectResolver do
+      authorize :read_project
+    end
+  end
+```
+
+The object found by the resolve call is used for authorization.
+
+This works for authorizing a single record, for authorizing
+collections, we should only load what the currently authenticated user
+is allowed to view. Preferably we use our existing finders for that.
+
+## Types
+
+When exposing a model through the GraphQL API, we do so by creating a
+new type in `app/graphql/types`.
+
+When exposing properties in a type, make sure to keep the logic inside
+the definition as minimal as possible. Instead, consider moving any
+logic into a presenter:
+
+```ruby
+class Types::MergeRequestType < BaseObject
+  present_using MergeRequestPresenter
+
+  name 'MergeRequest'
+end
+```
+
+An existing presenter could be used, but it is also possible to create
+a new presenter specifically for GraphQL.
+
+The presenter is initialized using the object resolved by a field, and
+the context.
+
+## Resolvers
+
+To find objects to display in a field, we can add resolvers to
+`app/graphql/resolvers`.
+
+Arguments can be defined within the resolver, those arguments will be
+made available to the fields using the resolver.
+
+We already have a `FullPathLoader` that can be included in other
+resolvers to quickly find Projects and Namespaces which will have a
+lot of dependant objects.
+
+To limit the amount of queries performed, we can use `BatchLoader`.
+
+## Testing
+
+_full stack_ tests for a graphql query or mutation live in
+`spec/requests/api/graphql`.
+
+When adding a query, the `a working graphql query` shared example can
+be used to test if the query renders valid results.
+
+Using the `GraphqlHelpers#all_graphql_fields_for`-helper, a query
+including all available fields can be constructed. This makes it easy
+to add a test rendering all possible fields for a query.