From 8630b8d499627a5eae8532491205592b43e2bc79 Mon Sep 17 00:00:00 2001 From: Soner Sayakci Date: Mon, 8 Jan 2024 15:56:56 +0100 Subject: [PATCH 01/11] add partial data loading --- .../general-concepts/partial-data-loading.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 guides/integrations-api/general-concepts/partial-data-loading.md diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md new file mode 100644 index 000000000..dbe067f4b --- /dev/null +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -0,0 +1,126 @@ +--- +nav: + title: Partial Data Loading + position: 50 + +--- + +# Partial Data Loading + +Partial Data Loading allows you to select specific fields of an entity to be returned by the API. This can be useful if you only need a few fields of an entity and don't want to load the whole entity. This can reduce the response size and improve the performance of your application. + +### Partial Data Loading vs Includes + +Partial Data Loading is different from the [includes](./search-criteria.md#includes-apialias) feature. While includes works as post output processing, so the complete entity or data is loaded in the backend side and then filtered, partial data loading works already on Database level. This means that the database only loads the requested fields and not the whole entity. + +## Usage + +```http +POST /api/search/currency +Authorization: Bearer ..... +Content-Type: application/json +Accept: application/json + +{ + "fields": [ + "name" + ] +} +``` + +```json +// response +{ + "total": 1, + "data": [ + { + "extensions": [], + "_uniqueIdentifier": "018cda3ac909712496bccc065acf0ff4", + "translated": { + "name": "US-Dollar" + }, + "id": "018cda3ac909712496bccc065acf0ff4", + "name": "US-Dollar", + "isSystemDefault": false, + "apiAlias": "currency" + } + ], + "aggregations": [] +} +``` + +Fields can reference also fields of associations like in this example the assigned salesChannel names of the currency. The API adds the necessary associations automatically for you. + +```http +POST /api/search/currency +Authorization: Bearer ..... +Content-Type: application/json +Accept: application/json + +{ + "fields": [ + "name", + "salesChannels.name" + ] +} +``` + +```json +// response +{ + "total": 1, + "data": [ + { + "extensions": [], + "_uniqueIdentifier": "018cda3ac909712496bccc065acf0ff4", + "translated": { + "name": "US-Dollar" + }, + "id": "018cda3ac909712496bccc065acf0ff4", + "name": "US-Dollar", + "salesChannels": [ + { + "extensions": [], + "_uniqueIdentifier": "018cda3af56670d6a3fa515a85967bd2", + "translated": { + "name": "Storefront" + }, + "id": "018cda3af56670d6a3fa515a85967bd2", + "name": "Storefront", + "apiAlias": "sales_channel" + } + ], + "isSystemDefault": false, + "apiAlias": "currency" + } + ], + "aggregations": [] +} +``` + +## Default fields + +Some fields are always loaded like the `id` or join relevant fields like foreign keys, these are necessary for the API to work correctly and can't be removed. + +## Runtime fields + +Some fields in the API are generated at runtime like `isSystemDefault` of the currency. These fields are loaded by default when the depending on data is available, otherwise they can be referenced in the `fields` parameter to force the API to load them. + +For custom entity definitions with Runtime flag, the depending on fields needs to be specified inside the constructor. See an example from the core: + +```php +protected function defineFields(): FieldCollection +{ + return new FieldCollection([ + (new IdField('id', 'id'))->addFlags(new ApiAware(), new PrimaryKey(), new Required()), + (new StringField('path', 'path'))->addFlags(new ApiAware()), + + // When this field is requested, we need the data of path field to generate the url + (new StringField('url', 'url'))->addFlags(new ApiAware(), new Runtime(['path'])), + ]); +} +``` + +## Limitations + +The current limitation of the Partial Data loading is that it only works on the Entity level. Any custom responses like a product detail page or CMS in the Store API can't be used with this feature, as the Store API needs the whole entity to generate the response. If you need a small response, we recommend to use the [includes](./search-criteria.md#includes-apialias) feature of the Search API. From d10368d991e99f3d6d798450b57c9f8a91f0c57d Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:25:13 +0100 Subject: [PATCH 02/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index dbe067f4b..4844cec1c 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -7,7 +7,7 @@ nav: # Partial Data Loading -Partial Data Loading allows you to select specific fields of an entity to be returned by the API. This can be useful if you only need a few fields of an entity and don't want to load the whole entity. This can reduce the response size and improve the performance of your application. +`Partial data loading` allows you to select specific fields of an entity to be returned by the API. This can be useful if you only need a few fields of an entity and don't want to load the whole entity. This can reduce the response size and improve the performance of your application. ### Partial Data Loading vs Includes From ed8bc3122eb67874e709e242e28c724be859ade9 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:25:29 +0100 Subject: [PATCH 03/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index 4844cec1c..b26aac4c6 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -49,7 +49,7 @@ Accept: application/json } ``` -Fields can reference also fields of associations like in this example the assigned salesChannel names of the currency. The API adds the necessary associations automatically for you. +Fields can also reference fields of associations like in this example the assigned salesChannel names of the currency. The API adds the necessary associations automatically. ```http POST /api/search/currency From dac261c9e4bcb3432fc47b80263be30ba892d3ff Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:25:38 +0100 Subject: [PATCH 04/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index b26aac4c6..3184ce7dc 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -106,7 +106,7 @@ Some fields are always loaded like the `id` or join relevant fields like foreign Some fields in the API are generated at runtime like `isSystemDefault` of the currency. These fields are loaded by default when the depending on data is available, otherwise they can be referenced in the `fields` parameter to force the API to load them. -For custom entity definitions with Runtime flag, the depending on fields needs to be specified inside the constructor. See an example from the core: +For custom entity definitions with runtime flag, the depending on fields needs to be specified inside the constructor. See an example from the core: ```php protected function defineFields(): FieldCollection From 4a9338cedd10b4dafea196ba142a1f16a8b46281 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:25:45 +0100 Subject: [PATCH 05/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index 3184ce7dc..4194f3334 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -123,4 +123,4 @@ protected function defineFields(): FieldCollection ## Limitations -The current limitation of the Partial Data loading is that it only works on the Entity level. Any custom responses like a product detail page or CMS in the Store API can't be used with this feature, as the Store API needs the whole entity to generate the response. If you need a small response, we recommend to use the [includes](./search-criteria.md#includes-apialias) feature of the Search API. +The current limitation of the `partial data loading` is that it only works on the Entity level. Any custom responses like a product detail page or CMS in the Store API can't be used with this feature, as the Store API needs the whole entity to generate the response. If you need a small response, we recommend to use the [includes](./search-criteria.md#includes-apialias) feature of the Search API. From b4a0a9756a531454d1a96167d0ec93621431253b Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:25:51 +0100 Subject: [PATCH 06/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index 4194f3334..a33e1975e 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -53,7 +53,7 @@ Fields can also reference fields of associations like in this example the assign ```http POST /api/search/currency -Authorization: Bearer ..... +Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json Accept: application/json From 74cdf3b79ff5b3dd667bf65b7ebedf8ed431e47e Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:25:57 +0100 Subject: [PATCH 07/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index a33e1975e..d64ac70a8 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -17,7 +17,7 @@ Partial Data Loading is different from the [includes](./search-criteria.md#inclu ```http POST /api/search/currency -Authorization: Bearer ..... +Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json Accept: application/json From ad79f579d8976037f61fcfcbfe1eda6a6e549e3f Mon Sep 17 00:00:00 2001 From: Shyim Date: Wed, 24 Jan 2024 10:29:07 +0100 Subject: [PATCH 08/11] Update guides/integrations-api/general-concepts/partial-data-loading.md Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- .../integrations-api/general-concepts/partial-data-loading.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index d64ac70a8..a1e6dca9f 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -9,9 +9,9 @@ nav: `Partial data loading` allows you to select specific fields of an entity to be returned by the API. This can be useful if you only need a few fields of an entity and don't want to load the whole entity. This can reduce the response size and improve the performance of your application. -### Partial Data Loading vs Includes +### Partial data loading vs Includes -Partial Data Loading is different from the [includes](./search-criteria.md#includes-apialias) feature. While includes works as post output processing, so the complete entity or data is loaded in the backend side and then filtered, partial data loading works already on Database level. This means that the database only loads the requested fields and not the whole entity. +`Partial data loading` is different from the [includes](./search-criteria.md#includes-apialias) feature. The `includes` works as post-output processing, so the complete entity or data is loaded in the backend side and then filtered, while `partial data loading` works already on database level. This means that the database only loads the requested fields and not the whole entity. ## Usage From 782e87f6e503e7027fb64cbae6a944460f7e3808 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:52:11 +0100 Subject: [PATCH 09/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index a1e6dca9f..abe60b659 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -104,7 +104,7 @@ Some fields are always loaded like the `id` or join relevant fields like foreign ## Runtime fields -Some fields in the API are generated at runtime like `isSystemDefault` of the currency. These fields are loaded by default when the depending on data is available, otherwise they can be referenced in the `fields` parameter to force the API to load them. +Some fields in the API are generated at runtime like `isSystemDefault` of the currency. These fields are loaded by default when the referenced data is available, otherwise they can be requested in the `fields` parameter to force the API to load them. For custom entity definitions with runtime flag, the depending on fields needs to be specified inside the constructor. See an example from the core: From 3cd74ea9773fbe9e490dcf20968796c143b88aa4 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:52:16 +0100 Subject: [PATCH 10/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index abe60b659..8c157f753 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -106,7 +106,7 @@ Some fields are always loaded like the `id` or join relevant fields like foreign Some fields in the API are generated at runtime like `isSystemDefault` of the currency. These fields are loaded by default when the referenced data is available, otherwise they can be requested in the `fields` parameter to force the API to load them. -For custom entity definitions with runtime flag, the depending on fields needs to be specified inside the constructor. See an example from the core: +For custom entity definitions with runtime flag, the referenced fields need to be specified inside the constructor. See an example from the core: ```php protected function defineFields(): FieldCollection From f4dfc0df3f39500ef1059937ecdc164d7266e1fe Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:53:11 +0100 Subject: [PATCH 11/11] Update guides/integrations-api/general-concepts/partial-data-loading.md --- .../integrations-api/general-concepts/partial-data-loading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/integrations-api/general-concepts/partial-data-loading.md index 8c157f753..c6dd529de 100644 --- a/guides/integrations-api/general-concepts/partial-data-loading.md +++ b/guides/integrations-api/general-concepts/partial-data-loading.md @@ -123,4 +123,4 @@ protected function defineFields(): FieldCollection ## Limitations -The current limitation of the `partial data loading` is that it only works on the Entity level. Any custom responses like a product detail page or CMS in the Store API can't be used with this feature, as the Store API needs the whole entity to generate the response. If you need a small response, we recommend to use the [includes](./search-criteria.md#includes-apialias) feature of the Search API. +The current limitation of the `partial data loading` is that it only works on the Entity level. Any custom responses like a product detail page or CMS in the Store API can't be used with this feature, as the Store API needs the whole entity to generate the response. If you need a small response, we recommend using the [includes](./search-criteria.md#includes-apialias) feature of the Search API.