Clarify populate usage

docusaurus/docs/dev-docs/api/rest.md

@@ -1,5 +1,5 @@
 ---
-title: REST API
+title: REST API reference
 description: Interact with your Content-Types using the REST API endpoints Strapi generates for you.
 displayed_sidebar: restApiSidebar
 

docusaurus/docs/dev-docs/api/rest/guides/intro.md

@@ -0,0 +1,17 @@
+---
+title: REST API Guides
+description: Deep dive into some specific REST API topics using guides that extensively explain some use cases or give step-by-step instructions.
+pagination_prev: dev-docs/api/rest
+pagination_next: dev-docs/api/rest/guides/understanding-populate
+---
+
+# REST API Guides
+
+The [REST API reference](/dev-docs/api/rest) documentation is meant to provide a quick reference for all the endpoints and parameters available. The following guides cover dedicated topics and provide detailed explanations (guides indicated with 🧠) or step-by-step instructions (guides indicated with 🛠️) for some use cases.
+
+<!-- <CustomDocCardsWrapper> -->
+
+<CustomDocCard emoji="🧠" title="Understanding populate" description="Learn what populating means and how you can use the populate parameter in your REST API queries to add additional fields to your responses." link="/dev-docs/api/rest/guides/understanding-populate" />
+<CustomDocCard emoji="🛠️" title="How to populate creator fields" description="Read step-by-step instructions on how to build a custom controller that leverages the populate parameter to add 'createdBy' and 'updatedBy' data to queries responses" link="/dev-docs/api/rest/guides/populate-creator-fields" />
+
+<!-- </CustomDocCardsWrapper> -->

docusaurus/docs/dev-docs/api/rest/guides/populate-creator-fields.md

@@ -0,0 +1,69 @@
+---
+title: How to populate creator fields
+description: Learn how to populate creator fields such as createdBy and updatedBy by creating a custom controller that leverages the populate parameter.
+---
+
+# 🛠️ How to populate creator fields such as `createdBy` and `updatedBy`
+
+The creator fields `createdBy` and `updatedBy` are removed from the [REST API](/dev-docs/api/rest) response by default. These 2 fields can be returned in the REST API by activating the `populateCreatorFields` parameter at the content-type level.
+
+:::note
+
+The `populateCreatorFields` property is not available to the GraphQL API.
+:::
+
+To add `createdBy` and `updatedBy` to the API response:
+
+1. Open the content-type `schema.json` file.
+2. Add `"populateCreatorFields": true` to the `options` object:
+
+  ```json
+  "options": {
+      "draftAndPublish": true,
+      "populateCreatorFields": true
+    },
+  ```
+
+3. Save the `schema.json`.
+4. Open the controller `[collection-name].js` file inside the corresponding API request.
+5. Add the following piece of code, and make sure you replace the `[collection-name].js` with proper collection name:
+
+  ```js
+  'use strict';
+  /**
+   *  [collection-name] controller
+   */
+  const { createCoreController } = require('@strapi/strapi').factories;
+  module.exports = createCoreController('api::[collection-name].[collection-name]', ({ strapi }) => ({
+    async find(ctx) {
+      // Calling the default core action
+      const { data, meta } = await super.find(ctx);
+      const query = strapi.db.query('api::[collection-name].[collection-name]');
+      await Promise.all(
+        data.map(async (item, index) => {
+          const foundItem = await query.findOne({
+            where: {
+              id: item.id,
+            },
+            populate: ['createdBy', 'updatedBy'],
+          });
+
+          data[index].attributes.createdBy = {
+            id: foundItem.createdBy.id,
+            firstname: foundItem.createdBy.firstname,
+            lastname: foundItem.createdBy.lastname,
+          };
+          data[index].attributes.updatedBy = {
+            id: foundItem.updatedBy.id,
+            firstname: foundItem.updatedBy.firstname,
+            lastname: foundItem.updatedBy.lastname,
+          };
+        })
+      );
+      return { data, meta };
+    },
+  }));
+  ```
+
+REST API requests using the `populate` parameter that include the `createdBy` or `updatedBy` fields will now populate these fields.
+