From 04727603ce3256a9cf4cd28f1a746990f5439a14 Mon Sep 17 00:00:00 2001
From: Alberto Vena <kennyadsl@gmail.com>
Date: Mon, 5 Jul 2021 17:48:20 +0200
Subject: [PATCH] Add a paragraph that describes how to filter products via API

Into the top level "wiki-style" REST API documentation section.
---
 api/openapi/main.hub.yml                |  6 +++---
 api/openapi/pagination-and-filtering.md | 23 +++++++++++++++++++++++
 api/openapi/pagination.md               |  7 -------
 3 files changed, 26 insertions(+), 10 deletions(-)
 create mode 100644 api/openapi/pagination-and-filtering.md
 delete mode 100644 api/openapi/pagination.md

diff --git a/api/openapi/main.hub.yml b/api/openapi/main.hub.yml
index be8e107f88d..975236b90a2 100644
--- a/api/openapi/main.hub.yml
+++ b/api/openapi/main.hub.yml
@@ -38,11 +38,11 @@ pages:
             path: /authentication
           data:
             $ref: ./authentication.md
-        - title: Pagination
+        - title: Pagination and Filtering
           route:
-            path: /pagination
+            path: /pagination-and-filtering
           data:
-            $ref: ./pagination.md
+            $ref: ./pagination-and-filtering.md
         - title: Errors
           route:
             path: /errors
diff --git a/api/openapi/pagination-and-filtering.md b/api/openapi/pagination-and-filtering.md
new file mode 100644
index 00000000000..51abdef4c75
--- /dev/null
+++ b/api/openapi/pagination-and-filtering.md
@@ -0,0 +1,23 @@
+# Pagination and Filtering
+
+## Pagination
+
+Most endpoints that return a collection are paginated. A paginated response contains metadata about the current page at the root level and the resources in the current page in a child key named after the resource (e.g. `orders`).
+
+You can pass the `page` and `per_page` parameters to set the current page and the desired number of items per page. Note that the default and the maximum number of items per page is decided at the application level.
+
+All pagination metadata is documented in the individual API endpoints, so take a look there if you're unsure what data you can expect.
+
+## Filtering
+
+Most endpoints that return a collection also have the ability to filter data using query params. This works taking advantage of the search filters provided by [Ransack](https://github.com/activerecord-hackery/ransack/).
+
+For example, if we want to retrieve only products that contain the word "Watch" in their title we can make the following request:
+
+```
+GET /products?q[name_cont]=Watch
+```
+
+The `name_cont` matcher will generate a query using `LIKE` to retrieve all the products that contain the value specified. For an extensive list of search matchers supported, please refer to the Ransack documentation.
+
+The result will be paginated as described in the paragraph above.
diff --git a/api/openapi/pagination.md b/api/openapi/pagination.md
deleted file mode 100644
index 07a4e8a9fb6..00000000000
--- a/api/openapi/pagination.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Pagination
-
-Most endpoints that return a collection are paginated. A paginated response contains metadata about the current page at the root level and the resources in the current page in a child key named after the resource (e.g. `orders`).
-
-You can pass the `page` and `per_page` parameters to set the current page and the desired number of items per page. Note that the default and the maximum number of items per page is decided at the application level.
-
-All pagination metadata is documented in the individual API endpoints, so take a look there if you're unsure what data you can expect.
\ No newline at end of file