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 + diff --git a/marketplace/eqp/v1/filtering.md b/marketplace/eqp/v1/filtering.md new file mode 100644 index 00000000000..cb37139047b --- /dev/null +++ b/marketplace/eqp/v1/filtering.md @@ -0,0 +1,67 @@ +--- +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 are passed to request a subset of the results. + +|Field|Type|Default|Description| +|-----|----|-------|-----------| +|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 comes 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.| + +For example, 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 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, without using filters: + +```HTTP +GET /rest/v1/products/packages/12345/ +``` + +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 zero 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](packages.html#get-package-details).