From ab22b345eb0482f0e304d6f5c92ca2ce1da2c131 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 13 Apr 2023 15:29:48 +0300 Subject: [PATCH] chore(docs): Generated API Reference (#3826) Co-authored-by: shahednasser --- docs/api/admin.oas.json | 2 +- docs/api/admin/openapi.yaml | 35 +++++++++++++++++++++++++++++++++++ docs/api/store.oas.json | 2 +- docs/api/store/openapi.yaml | 31 +++++++++++++++++++++++++++++++ 4 files changed, 68 insertions(+), 2 deletions(-) diff --git a/docs/api/admin.oas.json b/docs/api/admin.oas.json index fb56220788..20b4641b9a 100644 --- a/docs/api/admin.oas.json +++ b/docs/api/admin.oas.json @@ -3,7 +3,7 @@ "info": { "version": "1.0.0", "title": "Medusa Admin API", - "description": "API reference for Medusa's Admin endpoints. All endpoints are prefixed with `/admin`.\n\n## Authentication\n\nThere are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID.\n\n\n\n## Expanding Fields\n\nIn many endpoints you'll find an `expand` query parameter that can be passed to the endpoint. You can use the `expand` query parameter to unpack an entity's relations and return them in the response.\n\nPlease note that the relations you pass to `expand` replace any relations that are expanded by default in the request.\n\n### Expanding One Relation\n\nFor example, when you retrieve products, you can retrieve their collection by passing to the `expand` query parameter the value `collection`:\n\n```bash\ncurl \"http://localhost:9000/admin/products?expand=collection\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Expanding Multiple Relations\n\nYou can expand more than one relation by separating the relations in the `expand` query parameter with a comma.\n\nFor example, to retrieve both the variants and the collection of products, pass to the `expand` query parameter the value `variants,collection`:\n\n```bash\ncurl \"http://localhost:9000/admin/products?expand=variants,collection\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Prevent Expanding Relations\n\nSome requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?expand\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nThis would retrieve each product with only its properties, without any relations like `collection`.\n\n## Selecting Fields\n\nIn many endpoints you'll find a `fields` query parameter that can be passed to the endpoint. You can use the `fields` query parameter to specify which fields in the entity should be returned in the response.\n\nPlease note that if you pass a `fields` query parameter, only the fields you pass in the value along with the `id` of the entity will be returned in the response.\n\nAlso, the `fields` query parameter does not affect the expanded relations. You'll have to use the `expand` parameter instead.\n\n### Selecting One Field\n\nFor example, when you retrieve a list of products, you can retrieve only the titles of the products by passing `title` as a value to the `fields` query parameter:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields=title\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nAs mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter.\n\nYou can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields=title&expand\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Selecting Multiple Fields\n\nYou can pass more than one field by seperating the field names in the `fields` query parameter with a comma.\n\nFor example, to select the `title` and `handle` of products:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields=title,handle\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Retrieve Only the ID\n\nYou can pass an empty `fields` query parameter to return only the ID of an entity. For example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nYou can also pair with an empty `expand` query parameter to ensure that the relations aren't retrieved as well. For example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields&expand\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n## Query Parameter Types\n\nThis section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API endpoints and not using our JS Client. For example, when using cURL or Postman.\n\n### Strings\n\nYou can pass a string value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?title=Shirt\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nIf the string has any characters other than letters and numbers, you must encode them.\n\nFor example, if the string has spaces, you can encode the space with `+` or `%20`:\n\n```bash\ncurl \"http://localhost:9000/admin/products?title=Blue%20Shirt\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nYou can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded.\n\n### Integers\n\nYou can pass an integer value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?offset=1\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Boolean\n\nYou can pass a boolean value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?is_giftcard=true\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Date and DateTime\n\nYou can pass a date value in the form `=`. The date must be in the format `YYYY-MM-DD`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?created_at[lt]=2023-02-17\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nYou can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Array\n\nEach array value must be passed as a separate query parameter in the form `[]=`. You can also specify the index of each parameter in the brackets `[0]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nNote that the `-g` parameter passed to `curl` disables errors being thrown for using the brackets. Read more [here](https://curl.se/docs/manpage.html#-g).\n\n### Object\n\nObject parameters must be passed as separate query parameters in the form `[]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n## Pagination\n\n### Query Parameters\n\nIn listing endpoints, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`.\n\n`limit` is used to specify the maximum number of items that can be return in the response. `offset` is used to specify how many items to skip before returning the resulting entities.\n\nYou can use the `offset` query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.\n\nFor example, to limit the number of products returned in the List Products endpoint:\n\n```bash\ncurl \"http://localhost:9000/admin/products?limit=5\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Response Fields\n\nIn the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.\n\nSimilar to the query parameters, `limit` is the maximum number of items that can be returned in the response, and `field` is the number of items that were skipped before the entities in the result.\n\n`count` is the total number of available items of this entity. It can be used to determine how many pages are there.\n\nFor example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`.\n", + "description": "API reference for Medusa's Admin endpoints. All endpoints are prefixed with `/admin`.\n\n## Authentication\n\nThere are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID.\n\n\n\n## Expanding Fields\n\nIn many endpoints you'll find an `expand` query parameter that can be passed to the endpoint. You can use the `expand` query parameter to unpack an entity's relations and return them in the response.\n\nPlease note that the relations you pass to `expand` replace any relations that are expanded by default in the request.\n\n### Expanding One Relation\n\nFor example, when you retrieve products, you can retrieve their collection by passing to the `expand` query parameter the value `collection`:\n\n```bash\ncurl \"http://localhost:9000/admin/products?expand=collection\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Expanding Multiple Relations\n\nYou can expand more than one relation by separating the relations in the `expand` query parameter with a comma.\n\nFor example, to retrieve both the variants and the collection of products, pass to the `expand` query parameter the value `variants,collection`:\n\n```bash\ncurl \"http://localhost:9000/admin/products?expand=variants,collection\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Prevent Expanding Relations\n\nSome requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?expand\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nThis would retrieve each product with only its properties, without any relations like `collection`.\n\n## Selecting Fields\n\nIn many endpoints you'll find a `fields` query parameter that can be passed to the endpoint. You can use the `fields` query parameter to specify which fields in the entity should be returned in the response.\n\nPlease note that if you pass a `fields` query parameter, only the fields you pass in the value along with the `id` of the entity will be returned in the response.\n\nAlso, the `fields` query parameter does not affect the expanded relations. You'll have to use the `expand` parameter instead.\n\n### Selecting One Field\n\nFor example, when you retrieve a list of products, you can retrieve only the titles of the products by passing `title` as a value to the `fields` query parameter:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields=title\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nAs mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter.\n\nYou can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields=title&expand\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Selecting Multiple Fields\n\nYou can pass more than one field by seperating the field names in the `fields` query parameter with a comma.\n\nFor example, to select the `title` and `handle` of products:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields=title,handle\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Retrieve Only the ID\n\nYou can pass an empty `fields` query parameter to return only the ID of an entity. For example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nYou can also pair with an empty `expand` query parameter to ensure that the relations aren't retrieved as well. For example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?fields&expand\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n## Query Parameter Types\n\nThis section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API endpoints and not using our JS Client. For example, when using cURL or Postman.\n\n### Strings\n\nYou can pass a string value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?title=Shirt\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nIf the string has any characters other than letters and numbers, you must encode them.\n\nFor example, if the string has spaces, you can encode the space with `+` or `%20`:\n\n```bash\ncurl \"http://localhost:9000/admin/products?title=Blue%20Shirt\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nYou can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded.\n\n### Integers\n\nYou can pass an integer value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?offset=1\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Boolean\n\nYou can pass a boolean value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?is_giftcard=true\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Date and DateTime\n\nYou can pass a date value in the form `=`. The date must be in the format `YYYY-MM-DD`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?created_at[lt]=2023-02-17\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nYou can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Array\n\nEach array value must be passed as a separate query parameter in the form `[]=`. You can also specify the index of each parameter in the brackets `[0]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nNote that the `-g` parameter passed to `curl` disables errors being thrown for using the brackets. Read more [here](https://curl.se/docs/manpage.html#-g).\n\n### Object\n\nObject parameters must be passed as separate query parameters in the form `[]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n## Pagination\n\n### Query Parameters\n\nIn listing endpoints, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`.\n\n`limit` is used to specify the maximum number of items that can be return in the response. `offset` is used to specify how many items to skip before returning the resulting entities.\n\nYou can use the `offset` query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.\n\nFor example, to limit the number of products returned in the List Products endpoint:\n\n```bash\ncurl \"http://localhost:9000/admin/products?limit=5\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\n### Response Fields\n\nIn the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.\n\nSimilar to the query parameters, `limit` is the maximum number of items that can be returned in the response, and `field` is the number of items that were skipped before the entities in the result.\n\n`count` is the total number of available items of this entity. It can be used to determine how many pages are there.\n\nFor example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`.\n\n### Sort Order\n\nThe `order` field available on endpoints supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their `created_at` attribute by setting `order` to `created_at`:\n\n```bash\ncurl \"http://localhost:9000/admin/products?order=created_at\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nBy default, the sort direction will be ascending. To change it to descending, pass a dash (`-`) before the attribute name. For example:\n\n```bash\ncurl \"http://localhost:9000/admin/products?order=-created_at\" \\\n-H 'Authorization: Bearer {api_token}'\n```\n\nThis sorts the products by their `created_at` attribute in the descending order.\n", "license": { "name": "MIT", "url": "https://github.com/medusajs/medusa/blob/master/LICENSE" diff --git a/docs/api/admin/openapi.yaml b/docs/api/admin/openapi.yaml index 344994fa4e..dbad6cca7e 100644 --- a/docs/api/admin/openapi.yaml +++ b/docs/api/admin/openapi.yaml @@ -406,6 +406,41 @@ info: For example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`. + + + ### Sort Order + + + The `order` field available on endpoints supporting pagination allows you to + sort the retrieved items by an attribute of that item. For example, you can + sort products by their `created_at` attribute by setting `order` to + `created_at`: + + + ```bash + + curl "http://localhost:9000/admin/products?order=created_at" \ + + -H 'Authorization: Bearer {api_token}' + + ``` + + + By default, the sort direction will be ascending. To change it to + descending, pass a dash (`-`) before the attribute name. For example: + + + ```bash + + curl "http://localhost:9000/admin/products?order=-created_at" \ + + -H 'Authorization: Bearer {api_token}' + + ``` + + + This sorts the products by their `created_at` attribute in the descending + order. license: name: MIT url: https://github.com/medusajs/medusa/blob/master/LICENSE diff --git a/docs/api/store.oas.json b/docs/api/store.oas.json index 08da8aff5f..5b937a7cc5 100644 --- a/docs/api/store.oas.json +++ b/docs/api/store.oas.json @@ -3,7 +3,7 @@ "info": { "version": "1.0.0", "title": "Medusa Storefront API", - "description": "API reference for Medusa's Storefront endpoints. All endpoints are prefixed with `/store`.\n\n## Authentication\n\nTo send requests as an authenticated customer, you must use the Cookie Session ID.\n\n\n\n## Expanding Fields\n\nIn many endpoints you'll find an `expand` query parameter that can be passed to the endpoint. You can use the `expand` query parameter to unpack an entity's relations and return them in the response.\n\nPlease note that the relations you pass to `expand` replace any relations that are expanded by default in the request.\n\n### Expanding One Relation\n\nFor example, when you retrieve a product, you can retrieve its collection by passing to the `expand` query parameter the value `collection`:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection\"\n```\n\n### Expanding Multiple Relations\n\nYou can expand more than one relation by separating the relations in the `expand` query parameter with a comma.\n\nFor example, to retrieve both the variants and the collection of a product, pass to the `expand` query parameter the value `variants,collection`:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection\"\n```\n\n### Prevent Expanding Relations\n\nSome requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand\"\n```\n\nThis would retrieve the product with only its properties, without any relations like `collection`.\n\n## Selecting Fields\n\nIn many endpoints you'll find a `fields` query parameter that can be passed to the endpoint. You can use the `fields` query parameter to specify which fields in the entity should be returned in the response.\n\nPlease note that if you pass a `fields` query parameter, only the fields you pass in the value along with the `id` of the entity will be returned in the response.\n\nAlso, the `fields` query parameter does not affect the expanded relations. You'll have to use the `expand` parameter instead.\n\n### Selecting One Field\n\nFor example, when you retrieve a list of products, you can retrieve only the titles of the products by passing `title` as a value to the `fields` query parameter:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title\"\n```\n\nAs mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter.\n\nYou can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title&expand\"\n```\n\n### Selecting Multiple Fields\n\nYou can pass more than one field by seperating the field names in the `fields` query parameter with a comma.\n\nFor example, to select the `title` and `handle` of a product:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title,handle\"\n```\n\n### Retrieve Only the ID\n\nYou can pass an empty `fields` query parameter to return only the ID of an entity. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields\"\n```\n\nYou can also pair with an empty `expand` query parameter to ensure that the relations aren't retrieved as well. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields&expand\"\n```\n\n## Query Parameter Types\n\nThis section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API endpoints and not using our JS Client. For example, when using cURL or Postman.\n\n### Strings\n\nYou can pass a string value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?title=Shirt\"\n```\n\nIf the string has any characters other than letters and numbers, you must encode them.\n\nFor example, if the string has spaces, you can encode the space with `+` or `%20`:\n\n```bash\ncurl \"http://localhost:9000/store/products?title=Blue%20Shirt\"\n```\n\nYou can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded.\n\n### Integers\n\nYou can pass an integer value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?offset=1\"\n```\n\n### Boolean\n\nYou can pass a boolean value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?is_giftcard=true\"\n```\n\n### Date and DateTime\n\nYou can pass a date value in the form `=`. The date must be in the format `YYYY-MM-DD`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17\"\n```\n\nYou can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z\"\n```\n\n### Array\n\nEach array value must be passed as a separate query parameter in the form `[]=`. You can also specify the index of each parameter in the brackets `[0]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7\"\n```\n\nNote that the `-g` parameter passed to `curl` disables errors being thrown for using the brackets. Read more [here](https://curl.se/docs/manpage.html#-g).\n\n### Object\n\nObject parameters must be passed as separate query parameters in the form `[]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17\"\n```\n\n## Pagination\n\n### Query Parameters\n\nIn listing endpoints, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`.\n\n`limit` is used to specify the maximum number of items that can be return in the response. `offset` is used to specify how many items to skip before returning the resulting entities.\n\nYou can use the `offset` query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.\n\nFor example, to limit the number of products returned in the List Products endpoint:\n\n```bash\ncurl \"http://localhost:9000/store/products?limit=5\"\n```\n\n### Response Fields\n\nIn the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.\n\nSimilar to the query parameters, `limit` is the maximum number of items that can be returned in the response, and `field` is the number of items that were skipped before the entities in the result.\n\n`count` is the total number of available items of this entity. It can be used to determine how many pages are there.\n\nFor example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`.\n", + "description": "API reference for Medusa's Storefront endpoints. All endpoints are prefixed with `/store`.\n\n## Authentication\n\nTo send requests as an authenticated customer, you must use the Cookie Session ID.\n\n\n\n## Expanding Fields\n\nIn many endpoints you'll find an `expand` query parameter that can be passed to the endpoint. You can use the `expand` query parameter to unpack an entity's relations and return them in the response.\n\nPlease note that the relations you pass to `expand` replace any relations that are expanded by default in the request.\n\n### Expanding One Relation\n\nFor example, when you retrieve a product, you can retrieve its collection by passing to the `expand` query parameter the value `collection`:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection\"\n```\n\n### Expanding Multiple Relations\n\nYou can expand more than one relation by separating the relations in the `expand` query parameter with a comma.\n\nFor example, to retrieve both the variants and the collection of a product, pass to the `expand` query parameter the value `variants,collection`:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection\"\n```\n\n### Prevent Expanding Relations\n\nSome requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand\"\n```\n\nThis would retrieve the product with only its properties, without any relations like `collection`.\n\n## Selecting Fields\n\nIn many endpoints you'll find a `fields` query parameter that can be passed to the endpoint. You can use the `fields` query parameter to specify which fields in the entity should be returned in the response.\n\nPlease note that if you pass a `fields` query parameter, only the fields you pass in the value along with the `id` of the entity will be returned in the response.\n\nAlso, the `fields` query parameter does not affect the expanded relations. You'll have to use the `expand` parameter instead.\n\n### Selecting One Field\n\nFor example, when you retrieve a list of products, you can retrieve only the titles of the products by passing `title` as a value to the `fields` query parameter:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title\"\n```\n\nAs mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter.\n\nYou can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title&expand\"\n```\n\n### Selecting Multiple Fields\n\nYou can pass more than one field by seperating the field names in the `fields` query parameter with a comma.\n\nFor example, to select the `title` and `handle` of a product:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title,handle\"\n```\n\n### Retrieve Only the ID\n\nYou can pass an empty `fields` query parameter to return only the ID of an entity. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields\"\n```\n\nYou can also pair with an empty `expand` query parameter to ensure that the relations aren't retrieved as well. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields&expand\"\n```\n\n## Query Parameter Types\n\nThis section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API endpoints and not using our JS Client. For example, when using cURL or Postman.\n\n### Strings\n\nYou can pass a string value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?title=Shirt\"\n```\n\nIf the string has any characters other than letters and numbers, you must encode them.\n\nFor example, if the string has spaces, you can encode the space with `+` or `%20`:\n\n```bash\ncurl \"http://localhost:9000/store/products?title=Blue%20Shirt\"\n```\n\nYou can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded.\n\n### Integers\n\nYou can pass an integer value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?offset=1\"\n```\n\n### Boolean\n\nYou can pass a boolean value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?is_giftcard=true\"\n```\n\n### Date and DateTime\n\nYou can pass a date value in the form `=`. The date must be in the format `YYYY-MM-DD`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17\"\n```\n\nYou can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z\"\n```\n\n### Array\n\nEach array value must be passed as a separate query parameter in the form `[]=`. You can also specify the index of each parameter in the brackets `[0]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7\"\n```\n\nNote that the `-g` parameter passed to `curl` disables errors being thrown for using the brackets. Read more [here](https://curl.se/docs/manpage.html#-g).\n\n### Object\n\nObject parameters must be passed as separate query parameters in the form `[]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17\"\n```\n\n## Pagination\n\n### Query Parameters\n\nIn listing endpoints, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`.\n\n`limit` is used to specify the maximum number of items that can be return in the response. `offset` is used to specify how many items to skip before returning the resulting entities.\n\nYou can use the `offset` query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.\n\nFor example, to limit the number of products returned in the List Products endpoint:\n\n```bash\ncurl \"http://localhost:9000/store/products?limit=5\"\n```\n\n### Response Fields\n\nIn the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.\n\nSimilar to the query parameters, `limit` is the maximum number of items that can be returned in the response, and `field` is the number of items that were skipped before the entities in the result.\n\n`count` is the total number of available items of this entity. It can be used to determine how many pages are there.\n\nFor example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`.\n\n### Sort Order\n\nThe `order` field available on endpoints supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their `created_at` attribute by setting `order` to `created_at`:\n\n```bash\ncurl \"http://localhost:9000/list/products?order=created_at\"\n```\n\nBy default, the sort direction will be ascending. To change it to descending, pass a dash (`-`) before the attribute name. For example:\n\n```bash\ncurl \"http://localhost:9000/list/products?order=-created_at\"\n```\n\nThis sorts the products by their `created_at` attribute in the descending order.\n", "license": { "name": "MIT", "url": "https://github.com/medusajs/medusa/blob/master/LICENSE" diff --git a/docs/api/store/openapi.yaml b/docs/api/store/openapi.yaml index 1250218303..f603c6c6ab 100644 --- a/docs/api/store/openapi.yaml +++ b/docs/api/store/openapi.yaml @@ -373,6 +373,37 @@ info: For example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`. + + + ### Sort Order + + + The `order` field available on endpoints supporting pagination allows you to + sort the retrieved items by an attribute of that item. For example, you can + sort products by their `created_at` attribute by setting `order` to + `created_at`: + + + ```bash + + curl "http://localhost:9000/list/products?order=created_at" + + ``` + + + By default, the sort direction will be ascending. To change it to + descending, pass a dash (`-`) before the attribute name. For example: + + + ```bash + + curl "http://localhost:9000/list/products?order=-created_at" + + ``` + + + This sorts the products by their `created_at` attribute in the descending + order. license: name: MIT url: https://github.com/medusajs/medusa/blob/master/LICENSE