asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added details about expand, fields, and parameter types (#3325)

Browse Source
This commit is contained in:
Shahed Nasser
2023-02-23 17:12:51 +02:00
committed by GitHub
parent 8e5ebc9a1d
commit 8d453d35a9
2 changed files with 339 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
docs/api/admin-spec3-base.yaml
View File

@@ -15,21 +15,185 @@ info:
In 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.
For example, when you list customers you can also retrieve their groups by passing to the `expand` query parameter the value `groups`.
Please note that the relations you pass to `expand` replace any relations that are expanded by default in the request.
You can expand more than one relation by separating the relations in the `expand` query parameter with a comma. For example, to retrieve both the orders and the groups of a customer, pass to the `expand` query parameter the value `groups,orders`.
### Expanding One Relation
Please note that the parameters you pass to `expand` replace any relations that are expanded by default.
For example, when you retrieve products, you can retrieve their collection by passing to the `expand` query parameter the value `collection`:
```bash
curl "http://localhost:9000/admin/products?expand=collection" \
-H 'Authorization: Bearer {api_token}'
```
### Expanding Multiple Relations
You can expand more than one relation by separating the relations in the `expand` query parameter with a comma.
For example, to retrieve both the variants and the collection of products, pass to the `expand` query parameter the value `variants,collection`:
```bash
curl "http://localhost:9000/admin/products?expand=variants,collection" \
-H 'Authorization: Bearer {api_token}'
```
### Prevent Expanding Relations
Some requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.
For example:
```bash
curl "http://localhost:9000/admin/products?expand" \
-H 'Authorization: Bearer {api_token}'
```
This would retrieve each product with only its properties, without any relations like `collection`.
## Selecting Fields
In 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.
Please 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.
Also, the `fields` query parameter does not affect the expanded relations. You'll have to use the `expand` parameter instead.
### Selecting One Field
For 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:
```bash
curl "http://localhost:9000/admin/products?fields=title" \
-H 'Authorization: Bearer {api_token}'
```
As mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter.
You can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example:
```bash
curl "http://localhost:9000/admin/products?fields=title&expand" \
-H 'Authorization: Bearer {api_token}'
```
### Selecting Multiple Fields
You can pass more than one field by seperating the field names in the `fields` query parameter with a comma.
Only the fields you pass to `field` will be retrieved and returned in the response. Any fields that are returned by default will not be returned in this case. This does not affect relations.
For example, to select the `title` and `handle` of products:
For example, to only select the `title` and `description` fields of a product, pass to the `fields` query parameter the value `title,description`.
```bash
curl "http://localhost:9000/admin/products?fields=title,handle" \
-H 'Authorization: Bearer {api_token}'
```
### Retrieve Only the ID
You can pass an empty `fields` query parameter to return only the ID of an entity. For example:
```bash
curl "http://localhost:9000/admin/products?fields" \
-H 'Authorization: Bearer {api_token}'
```
You can also pair with an empty `expand` query parameter to ensure that the relations aren't retrieved as well. For example:
```bash
curl "http://localhost:9000/admin/products?fields&expand" \
-H 'Authorization: Bearer {api_token}'
```
## Query Parameter Types
This 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.
### Strings
You can pass a string value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/admin/products?title=Shirt" \
-H 'Authorization: Bearer {api_token}'
```
If the string has any characters other than letters and numbers, you must encode them.
For example, if the string has spaces, you can encode the space with `+` or `%20`:
```bash
curl "http://localhost:9000/admin/products?title=Blue%20Shirt" \
-H 'Authorization: Bearer {api_token}'
```
You can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded.
### Integers
You can pass an integer value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/admin/products?offset=1" \
-H 'Authorization: Bearer {api_token}'
```
### Boolean
You can pass a boolean value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/admin/products?is_giftcard=true" \
-H 'Authorization: Bearer {api_token}'
```
### Date and DateTime
You can pass a date value in the form `<parameter_name>=<value>`. The date must be in the format `YYYY-MM-DD`.
For example:
```bash
curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17" \
-H 'Authorization: Bearer {api_token}'
```
You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed.
For example:
```bash
curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
-H 'Authorization: Bearer {api_token}'
```
### Array
Each array value must be passed as a separate query parameter in the form `<parameter_name>[]=<value>`. You can also specify the index of each parameter in the brackets `<parameter_name>[0]=<value>`.
For example:
```bash
curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \
-H 'Authorization: Bearer {api_token}'
```
Note 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).
### Object
Object parameters must be passed as separate query parameters in the form `<parameter_name>[<key>]=<value>`.
For example:
```bash
curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17" \
-H 'Authorization: Bearer {api_token}'
```
## Pagination
@@ -41,11 +205,18 @@ info:
You 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.
For example, to limit the number of products returned in the List Products endpoint:
```bash
curl "http://localhost:9000/admin/products?limit=5" \
-H 'Authorization: Bearer {api_token}'
```
### Response Fields
In listing fields, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.
In the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.
Similarly 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.
Similar 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.
`count` is the total number of available items of this entity. It can be used to determine how many pages are there.

168
docs/api/store-spec3-base.yaml
View File

@@ -15,21 +15,169 @@ info:
In 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.
For example, when you list customers you can also retrieve their groups by passing to the `expand` query parameter the value `groups`.
Please note that the relations you pass to `expand` replace any relations that are expanded by default in the request.
You can expand more than one relation by separating the relations in the `expand` query parameter with a comma. For example, to retrieve both the orders and the groups of a customer, pass to the `expand` query parameter the value `groups,orders`.
### Expanding One Relation
Please note that the parameters you pass to `expand` replace any relations that are expanded by default.
For example, when you retrieve a product, you can retrieve its collection by passing to the `expand` query parameter the value `collection`:
```bash
curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection"
```
### Expanding Multiple Relations
You can expand more than one relation by separating the relations in the `expand` query parameter with a comma.
For example, to retrieve both the variants and the collection of a product, pass to the `expand` query parameter the value `variants,collection`:
```bash
curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection"
```
### Prevent Expanding Relations
Some requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.
For example:
```bash
curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand"
```
This would retrieve the product with only its properties, without any relations like `collection`.
## Selecting Fields
In 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.
Please 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.
Also, the `fields` query parameter does not affect the expanded relations. You'll have to use the `expand` parameter instead.
### Selecting One Field
For 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:
```bash
curl "http://localhost:9000/store/products?fields=title"
```
As mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter.
You can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example:
```bash
curl "http://localhost:9000/store/products?fields=title&expand"
```
### Selecting Multiple Fields
You can pass more than one field by seperating the field names in the `fields` query parameter with a comma.
Only the fields you pass to `field` will be retrieved and returned in the response. Any fields that are returned by default will not be returned in this case. This does not affect relations.
For example, to select the `title` and `handle` of a product:
For example, to only select the `title` and `description` fields of a product, pass to the `fields` query parameter the value `title,description`.
```bash
curl "http://localhost:9000/store/products?fields=title,handle"
```
### Retrieve Only the ID
You can pass an empty `fields` query parameter to return only the ID of an entity. For example:
```bash
curl "http://localhost:9000/store/products?fields"
```
You can also pair with an empty `expand` query parameter to ensure that the relations aren't retrieved as well. For example:
```bash
curl "http://localhost:9000/store/products?fields&expand"
```
## Query Parameter Types
This 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.
### Strings
You can pass a string value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/store/products?title=Shirt"
```
If the string has any characters other than letters and numbers, you must encode them.
For example, if the string has spaces, you can encode the space with `+` or `%20`:
```bash
curl "http://localhost:9000/store/products?title=Blue%20Shirt"
```
You can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded.
### Integers
You can pass an integer value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/store/products?offset=1"
```
### Boolean
You can pass a boolean value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/store/products?is_giftcard=true"
```
### Date and DateTime
You can pass a date value in the form `<parameter_name>=<value>`. The date must be in the format `YYYY-MM-DD`.
For example:
```bash
curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17"
```
You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed.
For example:
```bash
curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z"
```
### Array
Each array value must be passed as a separate query parameter in the form `<parameter_name>[]=<value>`. You can also specify the index of each parameter in the brackets `<parameter_name>[0]=<value>`.
For example:
```bash
curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"
```
Note 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).
### Object
Object parameters must be passed as separate query parameters in the form `<parameter_name>[<key>]=<value>`.
For example:
```bash
curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"
```
## Pagination
@@ -41,11 +189,17 @@ info:
You 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.
For example, to limit the number of products returned in the List Products endpoint:
```bash
curl "http://localhost:9000/store/products?limit=5"
```
### Response Fields
In listing fields, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.
In the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.
Similarly 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.
Similar 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.
`count` is the total number of available items of this entity. It can be used to determine how many pages are there.