From baa89e4ae802f3c9391af053c0e769b405ce4d0f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20K=C3=B6ller?= <mail@sebastian-koeller.de>
Date: Thu, 28 Jan 2021 08:28:05 +0100
Subject: [PATCH 1/3] Example of how to add extra key to response

I thought the documentation could get a bit improved here with an example of how exactly add an extra key to response, as up for today I never really figured it out and even then it took me some trying ;)
---
 docs/listeners/api.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/listeners/api.rst b/docs/listeners/api.rst
index 3454959d4..3979bbc20 100644
--- a/docs/listeners/api.rst
+++ b/docs/listeners/api.rst
@@ -154,6 +154,34 @@ Response format
 
 The default response format for both XML and JSON has two root keys, ``success`` and ``data``. It's possible to add
 your own root keys simply by using ``_serialize`` on the view var.
+For example you would like to add variable ``my_extra_data`` you have to add it to the configuration of the action like, this:
+
+.. code-block:: php
+
+class MyAction extends BaseAction 
+{
+
+  protected $_defaultConfig = [
+    'serialize' => [
+      'my_extra_data'
+    ],
+    // other stuff
+  ];
+  
+  protected function handle()
+  {
+    // do other stuff here
+    $this->_controller()->set('my_extra_data', 'This is my extra data I want to add to response');
+  }
+ 
+ The response will then look like:
+ 
+ .. code-block:: json
+ {
+  "success" : true,
+  "data" : {},
+  "my_extra_key" : "This is my extra data I want to add to response"
+ 
 
 JSON response
 ^^^^^^^^^^^^^

From af7f5fa0e6d89dd384a314455fed85bee8ef7a69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20K=C3=B6ller?= <mail@sebastian-koeller.de>
Date: Thu, 28 Jan 2021 08:32:27 +0100
Subject: [PATCH 2/3] codeblock fixed

---
 docs/listeners/api.rst | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/docs/listeners/api.rst b/docs/listeners/api.rst
index 3979bbc20..7789c0fc1 100644
--- a/docs/listeners/api.rst
+++ b/docs/listeners/api.rst
@@ -158,21 +158,22 @@ For example you would like to add variable ``my_extra_data`` you have to add it
 
 .. code-block:: php
 
-class MyAction extends BaseAction 
-{
-
-  protected $_defaultConfig = [
-    'serialize' => [
-      'my_extra_data'
-    ],
-    // other stuff
-  ];
-  
-  protected function handle()
+  <?php
+  class MyAction extends BaseAction 
   {
-    // do other stuff here
-    $this->_controller()->set('my_extra_data', 'This is my extra data I want to add to response');
-  }
+
+    protected $_defaultConfig = [
+      'serialize' => [
+        'my_extra_data'
+      ],
+      // other stuff
+    ];
+
+    protected function handle()
+    {
+      // do other stuff here
+      $this->_controller()->set('my_extra_data', 'This is my extra data I want to add to response');
+    }
  
  The response will then look like:
  

From 991b520c8e6cb0ed22ecd78568b8726bd924d15d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20K=C3=B6ller?= <mail@sebastian-koeller.de>
Date: Fri, 29 Jan 2021 13:13:52 +0100
Subject: [PATCH 3/3] updated code examples

I've update the code example to searilize variable in beforeFilter ans also added the method of doing that in a controller action, thanks to @irongomme.
---
 docs/listeners/api.rst | 50 +++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 20 deletions(-)

diff --git a/docs/listeners/api.rst b/docs/listeners/api.rst
index 7789c0fc1..1c88eaa1d 100644
--- a/docs/listeners/api.rst
+++ b/docs/listeners/api.rst
@@ -158,30 +158,40 @@ For example you would like to add variable ``my_extra_data`` you have to add it
 
 .. code-block:: php
 
-  <?php
-  class MyAction extends BaseAction 
-  {
-
-    protected $_defaultConfig = [
-      'serialize' => [
-        'my_extra_data'
-      ],
-      // other stuff
-    ];
+  class SomeController extends AppController {
+
+    public function beforeFilter(Event $event) {
+          $this->Crud->setConfig([
+                'serialize' => [
+                    'my_extra_data'
+                ],
+                'api' => [
+                    'success' => [
+                        'data' => [
+                            'entity' => [],
+                            'my_extra_data'
+                        ]
+                    ]
+                ]
+            ]);
+      }
+  }
+ 
+As an alternative use it in a controller action:
+ 
+.. code-block:: php
 
-    protected function handle()
-    {
-      // do other stuff here
-      $this->_controller()->set('my_extra_data', 'This is my extra data I want to add to response');
-    }
+  $this->set(compact('aggregation')); 
+  $this->Crud->action()->setConfig('serialize.aggregation', 'aggregation');
  
- The response will then look like:
+The response will then look like:
  
- .. code-block:: json
+.. code-block:: json
  {
-  "success" : true,
-  "data" : {},
-  "my_extra_key" : "This is my extra data I want to add to response"
+    "success" : true,
+    "data" : {},
+    "my_extra_key" : "This is my extra data I want to add to response"
+  }
  
 
 JSON response