Filtering and Sorting APIs Using the Postman API
Filtering and sorting APIs using the Postman API gives you the ability to decide which APIs you want to retrieve and how to organize them. You can easily apply a combination of filters using HTTP query parameters on the Postman API “Get all APIs” request. For instance, you can retrieve all the public APIs that have been updated during a specific time interval. With sorting, you can define which field you want to sort by and the sorting direction. By combining filtering and sorting, you can obtain the filtered list of APIs showing the most recently updated APIs first.
Even though filtering APIs by workspace was already possible, we eventually added the ability to filter by most other fields. Sorting, on the other hand, is a totally new feature that opens new possibilities. Together, filtering and sorting let you access your APIs in ways that make more sense to your particular use case.
With this latest feature, Ohpen, one of Postman’s customers, improved an internal tool to share and document OpenAPI specifications. “Being able to filter and sort the APIs during retrieval help us provide the best user experience to all API consumers when they are looking for a specific schema” says Fabrizio Ferri Benedetti, lead technical writer at Ohpen.
Keep reading to know more about how filtering and sorting work.
How to filter your APIs
Filtering works by reading the value of a parameter and applying it as the filter to the corresponding response field. If you employ more than one parameter, the filtering will be done using a logic AND on the combination of parameters. To get all the public APIs that have been updated during a specific time interval you would GET /apis?isPublic=true&since=2020-01-01T00:00:00+01:00&until=2020-02-01T00:00:00+01:00. Here are all the parameters that we’re adding that you can use to create your own filtering combinations:
| Name | Description | Example |
|---|---|---|
since |
Only return APIs that have been updated after this time. Time is represented using the ISO 8601 date and time format. | /apis?since=2020-01-01T00:00:00+01:00 |
until |
Only return APIs that have been updated before this time. Time is represented using the ISO 8601 date and time format. | /apis?until=2020-01-01T00:00:00+01:00 |
createdBy |
Only return APIs that have been created by the user ID represented by the given value. | /apis?createdBy=28613 |
updatedBy |
Only return APIs that have been updated by the user ID represented by the given value. | /apis?updatedBy=42847 |
isPublic |
Only return APIs with the corresponding privacy state. Public APIs have the isPublic value true; private APIs have the isPublic value false. |
/apis?isPublic=true |
name |
Only return APIs whose name includes the given value. Matching is case insensitive. | /apis?name=example |
summary |
Only return APIs whose summary includes the given value. Matching is case insensitive. | /apis?summary=example |
description |
Only return APIs whose description includes the given value. Matching is case insensitive. | /apis?description=example |
How to sort your APIs
Sorting works by reading the value of a parameter that defines which field is used to sort the results. The value of another parameter defines the sorting direction that can be ascending or descending. Unlike filtering, where you can combine multiple parameters, sorting is limited to a single parameter at a time. You can, however, combine filtering and sorting to retrieve the results. To retrieve the list of public APIs that have been updated during a specific time interval, showing the most recently updated first, you would GET /apis?isPublic=true&since=2020-01-01T00:00:00+01:00&sort=updatedAt. These are the parameters that let you control how you want the sorting feature to behave:
| Name | Description | Example |
|---|---|---|
sort |
The value of sort can be one of the names of the fields included in the response. |
/apis?sort=updatedAt |
direction |
The sorting direction, which can be ascending or descending. The value can be asc to specify an ascending direction or desc to specify a descending direction. If none is specified, the default sorting direction is descending for timestamp and numeric fields and ascending otherwise. An ID is not considered a numeric field. |
/apis?sort=updatedAt&direction=asc |
Try it yourself
We’ve added the ability to filter and sort APIs using the Postman API /apis endpoint. Filtering works by using a combination of GET parameters, one for each field that you want to sort by. You can specify sorting for a single field at a time, and you can choose to use an ascending or descending direction. By combining filtering and sorting, you’ll be able to fine-tune the way you retrieve APIs and offer the best experience to your own users. You can try it yourself by opening the “Get all APIs” request and fine-tune it to your needs.
How to filter a Date range Data’s by using Query Params
‘/apis?sort=created_date_time&direction=desc&access_token=Some_Token&meta=filter_count’
I am using this filter and the data received in Json is sorted with “Created_date_time” but it is not in descending order. I need newest first but getting oldest item first.
Could you please help me fix this. How can I resolve this.