From bc240d4744bce22c111e12366f9541a1af349555 Mon Sep 17 00:00:00 2001 From: Dewi Morgan Date: Fri, 1 Nov 2019 06:33:11 -0500 Subject: [PATCH 1/4] Add new file filtering.md --- marketplace/eqp/v1/filtering.md | 68 +++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 marketplace/eqp/v1/filtering.md diff --git a/marketplace/eqp/v1/filtering.md b/marketplace/eqp/v1/filtering.md new file mode 100644 index 00000000000..35276e7a819 --- /dev/null +++ b/marketplace/eqp/v1/filtering.md @@ -0,0 +1,68 @@ +--- +group: marketplace-api +title: Filtering +--- + +Some GET batch request endpoints support sorting, filtering, and pagination. + +Currently, the files endpoints support only pagination, while package endpoints support all three. + +## Paginating batch requests + +The following GET request parameters can be passed, to request a subset of the expected results. + +|Field|Type|Default|Description| +|-----|----|-------|-----------| +|offset|int|0|Which record in a list to begin the page from. The list starts at 0.| +|limit|int|20|How many records to return in the requested batch, starting from `offset`. -1 will return all remaining records.| + +The result will also come with a header `X-Total-Count`, which gives the number of total records. + +## Sorting batch requests + +If a field is listed as filterable, it is also sortable. To sort, pass in the `sort` GET parameter: + +|Field|Type|Description| +|-----|----|-----------| +|sort|string|Comma-separated list of field names to sort by. Fields may be prefixed with '-' to sort in descending order, or '+' for ascending.| + +So to sort all versions of all packages, M2 packages first, then M1, +grouped alphabetically by name, with newest packages first: + +```HTTP +GET /rest/v1/products/packages/?sort=-platform,+name,-version +``` + +## Filtering batch requests + +You can use many response fields as filters in the batch GET request. + +For example, to get a package with the submission_id "12345", one way is +to call the single-object convenience endpoint like so, without using filters: + +```HTTP +GET /rest/v1/products/packages/12345/ +``` + +But you can instead call the batch endpoint to return a list and filter it by submission_id, +so that the list contains only one item: + +```HTTP +GET /rest/v1/products/packages/?submission_id=12345 +``` + +The difference is that the first returns a single object or an error, while the second returns a list containing or one elements. + +The following request filters all `themes` sorted by `platform` in ascending order and `created_time` in descending order: + +**Request** + +```bash +curl -X GET \ + -H 'Authorization: Bearer baGXoStRuR9VCDFQGZNzgNqbqu5WUwlr.cAxZJ9m22Le7' \ + https://developer-api.magento.com/rest/v1/products/packages?type=theme&sort=+platform,-created_time +``` + +**Response** + +A list of theme packages can be returned in the same way as described in [Get package details](#get-package-details). From f33902401b013ddd7e8f09e795e8d54be8451f99 Mon Sep 17 00:00:00 2001 From: Dewi Morgan Date: Fri, 1 Nov 2019 06:34:30 -0500 Subject: [PATCH 2/4] Add filtering to the index --- _data/toc/marketplace-api.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/_data/toc/marketplace-api.yml b/_data/toc/marketplace-api.yml index e7d89947a89..0351194a6e2 100644 --- a/_data/toc/marketplace-api.yml +++ b/_data/toc/marketplace-api.yml @@ -24,3 +24,8 @@ pages: - label: Reports url: /marketplace/eqp/v1/reports.html versionless: true + + - label: Filtering + url: /marketplace/eqp/v1/filtering.html + versionless: true + From f208db38554e335363d7bb1514ad675369b16075 Mon Sep 17 00:00:00 2001 From: Dewi Morgan Date: Fri, 1 Nov 2019 06:40:51 -0500 Subject: [PATCH 3/4] Fix broken link --- marketplace/eqp/v1/filtering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/marketplace/eqp/v1/filtering.md b/marketplace/eqp/v1/filtering.md index 35276e7a819..f6e437b495c 100644 --- a/marketplace/eqp/v1/filtering.md +++ b/marketplace/eqp/v1/filtering.md @@ -65,4 +65,4 @@ curl -X GET \ **Response** -A list of theme packages can be returned in the same way as described in [Get package details](#get-package-details). +A list of theme packages can be returned in the same way as described in [Get package details](packages.html#get-package-details). From 29284055e607fbb815c85ea81274224b62677c8d Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Fri, 1 Nov 2019 08:51:06 -0500 Subject: [PATCH 4/4] Grammar and formatting --- marketplace/eqp/v1/filtering.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/marketplace/eqp/v1/filtering.md b/marketplace/eqp/v1/filtering.md index f6e437b495c..cb37139047b 100644 --- a/marketplace/eqp/v1/filtering.md +++ b/marketplace/eqp/v1/filtering.md @@ -5,18 +5,18 @@ title: Filtering Some GET batch request endpoints support sorting, filtering, and pagination. -Currently, the files endpoints support only pagination, while package endpoints support all three. +Currently, the `files` endpoints support only pagination, while package endpoints support all three. ## Paginating batch requests -The following GET request parameters can be passed, to request a subset of the expected results. +The following GET request parameters are passed to request a subset of the results. |Field|Type|Default|Description| |-----|----|-------|-----------| -|offset|int|0|Which record in a list to begin the page from. The list starts at 0.| -|limit|int|20|How many records to return in the requested batch, starting from `offset`. -1 will return all remaining records.| +|offset|int|0|The record in the list from which to begin. The list starts at 0.| +|limit|int|20|Number of records to return, starting from `offset`. -1 will return all remaining records.| -The result will also come with a header `X-Total-Count`, which gives the number of total records. +The result comes with a header `X-Total-Count`, which gives the number of total records. ## Sorting batch requests @@ -26,7 +26,7 @@ If a field is listed as filterable, it is also sortable. To sort, pass in the `s |-----|----|-----------| |sort|string|Comma-separated list of field names to sort by. Fields may be prefixed with '-' to sort in descending order, or '+' for ascending.| -So to sort all versions of all packages, M2 packages first, then M1, +For example, to sort all versions of all packages, M2 packages first, then M1, grouped alphabetically by name, with newest packages first: ```HTTP @@ -35,24 +35,23 @@ GET /rest/v1/products/packages/?sort=-platform,+name,-version ## Filtering batch requests -You can use many response fields as filters in the batch GET request. +You can use multiple response fields as filters in batch GET requests. For example, to get a package with the submission_id "12345", one way is -to call the single-object convenience endpoint like so, without using filters: +to call the single-object convenience endpoint, without using filters: ```HTTP GET /rest/v1/products/packages/12345/ ``` -But you can instead call the batch endpoint to return a list and filter it by submission_id, +Or alternatively, call the batch endpoint to return a list and filter it by `submission_id`, so that the list contains only one item: ```HTTP GET /rest/v1/products/packages/?submission_id=12345 ``` -The difference is that the first returns a single object or an error, while the second returns a list containing or one elements. - +The difference is that the first returns a single object or an error, while the second returns a list containing zero or one elements. The following request filters all `themes` sorted by `platform` in ascending order and `created_time` in descending order: **Request**