2 files changed, 68 insertions, 0 deletions
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..4d73efa3f71
--- /dev/null
+++ b/doc/development/api_graphql_styleguide.md
@@ -0,0 +1,66 @@
+# GraphQL API
+
+## Authentication
+
+Authentication happens through the `GrapqlController`, 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
+Types::QueryType = GraphQL::ObjectType.define do
+  name 'Query'
+
+  field :project, Types::ProjectType do
+    argument :full_path, !types.ID do
+      description 'The full path of the project, e.g., "gitlab-org/gitlab-ce"'
+    end
+
+    authorize :read_project
+
+    resolve Loaders::FullPathLoader[:project]
+  end
+end
+```
+
+The object found by the resolve call is used for authorization.
+
+
+## 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
+Types::MergeRequestType = GraphQL::ObjectType.define do
+  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.
+
+## Testing
+
+_full stack_ tests for a graphql query or mutation live in
+`spec/requests/graphql`.
+
+When adding a query, the `a working graphql query` shared example can
+be used to test the query, it expects a valid `query` to be available
+in the spec.