diff --git a/www/apps/api-reference/app/_mdx/admin.mdx b/www/apps/api-reference/app/_mdx/admin.mdx index 44a23dc943..2dc1a7dda5 100644 --- a/www/apps/api-reference/app/_mdx/admin.mdx +++ b/www/apps/api-reference/app/_mdx/admin.mdx @@ -199,17 +199,7 @@ x-no-compression: true ## Select Fields and Relations Many API Routes accept a `fields` query that allows you to select which fields and relations should be returned in a record. - - - - -When you pass the `fields` query, only specified fields and relations, along with the `id`, are retrieved in the result. - - - -### Select Multiple Fields - -Separate the fields and relations you want to select with a comma. +Fields and relations are separated by a comma `,`. For example: @@ -220,12 +210,21 @@ curl 'localhost:9000/admin/products?fields=title,handle' \ This returns only the `title` and `handle` fields of a product. +### Fields Operator + +By default, only the selected fields and relations are returned in the response. + +Before every field or relation, you can pass one of the following operators to change the default behavior: + +- `+`: Add the field to the fields returned by default. For example, `+title` returns the `title` field along with the fields returned by default. +- `-`: Remove the field from the fields returned by default. For example, `-title` removes the `title` field from the fields returned by default. + ### Select Relations -To select a relation, pass to `fields` the relation name prefixed by `.*`. For example: +To select a relation, pass to `fields` the relation name prefixed by `*`. For example: ```bash -curl 'localhost:9000/admin/products?fields=variants.*' \ +curl 'localhost:9000/admin/products?fields=*variants' \ -H 'Authorization: Bearer {jwt_token}' ``` @@ -233,9 +232,9 @@ This returns the variants of each product. ### Select Fields in a Relation -The `.*` suffix selects all fields of the relation's data model. +The `*` prefix selects all fields of the relation's data model. -To select a specific field, change the `*` to the field's name. +To select a specific field, pass a `.` suffix instead of the `*` prefix. For example, `variants.title`. To specify multiple fields, pass each of the fields with the `.` format, separated by a comma. diff --git a/www/apps/api-reference/app/_mdx/store.mdx b/www/apps/api-reference/app/_mdx/store.mdx index 277eab62e9..52164214f7 100644 --- a/www/apps/api-reference/app/_mdx/store.mdx +++ b/www/apps/api-reference/app/_mdx/store.mdx @@ -213,51 +213,47 @@ x-no-compression: true ## Select Fields and Relations Many API Routes accept a `fields` query that allows you to select which fields and relations should be returned in a record. - - - - -When you pass the `fields` query, only specified fields and relations, along with the `id`, are retrieved in the result. - - - -### Select Multiple Fields - -Separate the fields and relations you want to select with a comma. +Fields and relations are separated by a comma `,`. For example: ```bash -curl 'localhost:9000/store/products?fields=title,handle' \ --H 'Authorization: Bearer {jwt_token}' +curl 'localhost:9000/store/products?fields=title,handle' ``` This returns only the `title` and `handle` fields of a product. +### Fields Operator + +By default, only the selected fields and relations are returned in the response. + +Before every field or relation, you can pass one of the following operators to change the default behavior: + +- `+`: Add the field to the fields returned by default. For example, `+title` returns the `title` field along with the fields returned by default. +- `-`: Remove the field from the fields returned by default. For example, `-title` removes the `title` field from the fields returned by default. + ### Select Relations -To select a relation, pass to `fields` the relation name prefixed by `.*`. For example: +To select a relation, pass to `fields` the relation name prefixed by `*`. For example: ```bash -curl 'localhost:9000/store/products?fields=variants.*' \ --H 'Authorization: Bearer {jwt_token}' +curl 'localhost:9000/store/products?fields=*variants' ``` This returns the variants of each product. ### Select Fields in a Relation -The `.*` suffix selects all fields of the relation's data model. +The `*` prefix selects all fields of the relation's data model. -To select a specific field, change the `*` to the field's name. +To select a specific field, pass a `.` suffix instead of the `*` prefix. For example, `variants.title`. To specify multiple fields, pass each of the fields with the `.` format, separated by a comma. For example: ```bash -curl 'localhost:9000/store/products?fields=variants.title,variants.sku' \ --H 'Authorization: Bearer {jwt_token}' +curl 'localhost:9000/store/products?fields=variants.title,variants.sku' ``` This returns the variants of each product, but the variants only have their `id`, `title`, and `sku` fields. The `id` is always included. @@ -435,8 +431,7 @@ Use the `offset` query parameter to change between pages. For example, if the li For example: ```bash -curl "http://localhost:9000/store/products?limit=5" \ --H 'Authorization: Bearer {jwt_token}' +curl "http://localhost:9000/store/products?limit=5" ``` @@ -465,8 +460,7 @@ sort the retrieved items by a field of that item. For example, pass the query parameter `order=created_at` to sort products by their `created_at` field: ```bash -curl "http://localhost:9000/store/products?order=created_at" \ --H 'Authorization: Bearer {jwt_token}' +curl "http://localhost:9000/store/products?order=created_at" ``` By default, the sort direction is ascending. To change it to @@ -475,8 +469,7 @@ descending, pass a dash (`-`) before the field name. For example: ```bash -curl "http://localhost:9000/store/products?order=-created_at" \ --H 'Authorization: Bearer {jwt_token}' +curl "http://localhost:9000/store/products?order=-created_at" ```