Filtering and Sorting APIs Using the Postman API


Reading Time: 3 min.

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:

NameDescriptionExample
sinceOnly 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
untilOnly 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
createdByOnly return APIs that have been created by the user ID represented by the given value./apis?createdBy=28613
updatedByOnly return APIs that have been updated by the user ID represented by the given value./apis?updatedBy=42847
isPublicOnly return APIs with the corresponding privacy state. Public APIs have the isPublic value true; private APIs have the isPublic value false./apis?isPublic=true
nameOnly return APIs whose name includes the given value. Matching is case insensitive./apis?name=example
summaryOnly return APIs whose summary includes the given value. Matching is case insensitive./apis?summary=example
descriptionOnly 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:

NameDescriptionExample
sortThe value of sort can be one of the names of the fields included in the response./apis?sort=updatedAt
directionThe 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.

+6

  

What do you think about this topic? Tell us in a comment below.

Comments

Your email address will not be published. Required fields are marked *



This site uses Akismet to reduce spam. Learn how your comment data is processed.

You might also like: