From ace6badfedcdbebbee262141c0ebf279887d7c61 Mon Sep 17 00:00:00 2001
From: Jake Barnby <jakeb994@gmail.com>
Date: Tue, 12 Jul 2022 17:06:11 +1200
Subject: [PATCH] Doc updates

---
 app/controllers/api/graphql.php | 18 +++++++++---------
 docs/services/graphql.md        |  8 ++++++++
 2 files changed, 17 insertions(+), 9 deletions(-)
 create mode 100644 docs/services/graphql.md

diff --git a/app/controllers/api/graphql.php b/app/controllers/api/graphql.php
index 1f91149448..8951bdf669 100644
--- a/app/controllers/api/graphql.php
+++ b/app/controllers/api/graphql.php
@@ -27,9 +27,9 @@ App::get('/v1/graphql')
     ->label('sdk.response.model', Response::MODEL_ANY)
     ->label('abuse-limit', 60)
     ->label('abuse-time', 60)
-    ->param('query', '', new Text(4096), 'The query to execute. Max 1024 chars.')
-    ->param('operationName', null, new Text(256), 'Name of the operation to execute', true)
-    ->param('variables', [], new JSON(), 'Variables to use in the operation', true)
+    ->param('query', '', new Text(2048), 'The query to execute. Max 2048 chars')
+    ->param('operationName', null, new Text(512), 'Name of the operation to execute. Required if multiple operations are provided', true)
+    ->param('variables', [], new JSON(), 'Map of variables to use as replacement values in the query', true)
     ->inject('request')
     ->inject('response')
     ->inject('utopia')
@@ -52,11 +52,11 @@ App::post('/v1/graphql')
     ->label('sdk.response.model', Response::MODEL_ANY)
     ->label('abuse-limit', 60)
     ->label('abuse-time', 60)
-    ->param('query', '', new Text(4096), 'The query to execute. Max 1024 chars.', true)
-    ->param('operationName', null, new Text(256), 'Name of the operation to execute', true)
-    ->param('variables', [], new JSON(), 'Variables to use in the operation', true)
-    ->param('operations', '', new Text(4096), 'Variables to use in the operation', true)
-    ->param('map', '', new Text(1024), 'Variables to use in the operation', true)
+    ->param('query', '', new Text(2048), 'The query to execute. Max 1024 chars. Required if the request content type is "application/json"', true)
+    ->param('operationName', null, new Text(512), 'Name of the operation to execute. Required if multiple operations are provided', true)
+    ->param('variables', [], new JSON(), 'Map of variables to use as replacement values in the query', true)
+    ->param('operations', '', new Text(4096), 'JSON encoded query and variables with nulled file values. Required if the request content type "multipart/form-data"', true)
+    ->param('map', '', new Text(1024), 'Map of form-data filenames to the operations dot-path to inject the file to. For example: "variables.file"', true)
     ->inject('request')
     ->inject('response')
     ->inject('promiseAdapter')
@@ -85,8 +85,8 @@ function graphqlRequest(
     }
 
     if (\str_starts_with($contentType, 'multipart/form-data')) {
-        $map = \json_decode($map, true);
         $operations = \json_decode($operations, true);
+        $map = \json_decode($map, true);
         foreach ($map as $fileKey => $locations) {
             foreach ($locations as $location) {
                 $items = &$operations;
diff --git a/docs/services/graphql.md b/docs/services/graphql.md
new file mode 100644
index 0000000000..ffdd58df0a
--- /dev/null
+++ b/docs/services/graphql.md
@@ -0,0 +1,8 @@
+The GraphQL services allows you to manipulate your Appwrite instance through a single endpoint using GraphQL queries and mutations, asking for exactly what you need and nothing more. You can perform any action available in the REST API, as well as directly manipulate your custom collections.
+
+> ## GraphQL API vs REST API
+> The major difference comes from the way the data is returned. GraphQL returns the data in a structured format, giving you only the nodes you ask for, while REST returns the data in a flat format.
+> 
+> GraphQL has a single endpoint for all queries and mutations, including uploads and downloads, while the REST API has multiple endpoints for each type of action.
+> 
+> GraphQL requests are more flexible and can be _much_ more efficient than the REST API.
\ No newline at end of file