Flexible Querying with the Quickstart API

By Lana Lee posted 05-01-2023 12:57


On April 27th, the Zuora Community hosted a Developer Experience Table Talk with @Alex Knights, Senior Product Manager of Developer Experience, @Izzy Johnson, Tech Lead Developer Experience and @Wes Mena, Developer Experience Software Engineer on flexible querying with the Quickstart API.

The session began with a feature review where Alex gave an introduction to the flexible querying capabilities of the v2 API. There are 5 query parameters you need to know about in order to unlock the flexible querying capabilities of the Quickstart API: Expand, Filter, Fields, Sort, and Page Size.

1. Expand

By expanding objects in responses using the Quickstart API, you can reduce the number of requests you make to Zuora. This action can increase the performance of your system by addressing the n+1 problem with API requests. Please note that everything we are showing you here applies to write requests as well as read requests.

All objects in the Quickstart API have unique IDs you can use to retrieve, update and delete these objects. The Quickstart API also uses these IDs to link related objects together. An invoice, for example, links to a customer account by the account_id.

It’s important to note that expansion can speed up your integration by decreasing the number of API requests you make. While we have optimized many of the most common aggregate queries, sometimes these queries may impact the latency of a request. To keep requests fast, we recommend limiting the number of nested expansions on list requests and only expand objects that you’re actually using.

Most related object properties can be expanded - these are documented in the Expand Responses section of the Quickstart API Tutorials in the Developer Center. We have received feedback that we should document these in the API Reference itself and we intend to do that soon.

Using Expand: Please see the presentation and video below for an example of using Expand. 

2. Filter

WIth this parameter, you may filter lists using the following operators:

  • equality 

  • inequality 

  • starts with 

  • less than 

  • greater than

  • In (coming soon)

3. Fields

Using the fields query parameter can reduce request latency and eliminate over-fetching, i.e. receiving data in a response you don’t use. Additionally, you can specify the fields you want in a response and exclude all other object properties with

  • read or write requests

  • the properties of related objects

  • distantly-related objects

  • the properties of the objects in a list

Accepted field[] values - which is nearly all field values, with the exception of nested fields - are documented for each object in the QUERY PARAMETERS section of each API method.

4. Sort

By default, we sort lists by updated_time descending but with the ascending operator, you can reverse the default sort order or use the descending operator to, for example, sort a list of invoices by invoice_number. Similarly, you can sort string fields, date and time fields, and number fields.

5. Page Size

The page size query parameter determines the maximum number of results that will be returned on a single page when retrieving lists. You may set the page size to anything between 1 and 50. Here we have set it to 2. 

Learn More

View Presentation

Flexible Querying with the Quickstart API - April 2023

Join the Zuora Developer Group 

The Community's Developer group  is the place where you can connect with others who are using Zuora’s APIs like you. We also post updates about the API changelog and will also share when the next Developer Table Talk will take place.