Skip to content

Querying Sheetlabs APIs (GET)

To retrieve results from a Sheetlabs API, simply make an HTTP GET request to the endpoint. For example:

curl "https://sheetlabs.com/ACME/getDomain"

There are many additional options and parameters that you can supply when querying a Sheetlabs API, which are addressed in the remainder of this section.

Response formats and structure

Sheetlabs APIs respond in JSON format by default. You can optionally request an XML response by appending ".xml" to your API call. For example:

curl "https://sheetlabs.com/ACME/getDomain.xml"

The following applies to all response formats:

  • All formats return an array of elements as the outermost object (even if only one element is always returned).
  • Fields may contain NULL values, so be sure that your client can handle NULL values.

Searching and filtering

If the API you’re using supports filtering, then the filterable parameters will be listed in the API documentation. Some APIs will use filters that are mandatory (i.e. you must provide a value for them), whilst others will allow optional filters.

All filters must be specified in the query string. You will need to ensure that you URL encode your filters.

The following types of filters may be used:

Exact match

Our sample API allows filtering by domain name. An example query that uses this filter would be:

curl https://sheetlabs.com/ACME/getDomain?domain=apple.com

Partial match (wildcard)

Some APIs may allow searching by partial values on string fields. This is commonly known as wildcard searching. If the API you’re using allows this, then you can use the asterisk character (*) to achieve this.

curl "https://sheetlabs.com/ACME/getDomain?domain=apple*"

Filtering by number or date ranges

Some APIs may allow searching by ranges, which is supported for numerical and date fields. If the API you’re using allows this, then you can use two period chracters (..) between the start and end values to indicate the range you want to search for.

curl https://sheetlabs.com/ACME/getDomain?date=1987-01-01..1987-03-01

Multiple parameters

You may provide multiple filter parameters. Results will only be returned that match all of the parameters (i.e. it is a logical AND). For example:

curl "https://sheetlabs.com/ACME/getDomain?date=1987-01-01..1987-03-01&domain=*.com"

Pagination

You may wish to limit the number of results that the API will return in one go. Additionally, you may wish to define an offset from the start of the result set. Using these two parameters in tandem allows you to effectively page between results.

The parameters that configure this are as follows:

  • _limit: Limits the number of results returned to the specified number (must be an integer). For example, if you set the limit to 10 then you will always get 10 (or fewer) results returned.
  • _offset: Sets the offset at which to begin returning results. For example, if you set the offset to 5 then the first 5 results will be skipped. You must provide a _limit if you use this option.

For example:

curl "https://sheetlabs.com/ACME/getDomain?_limit=5&_offset=2"

Sorting results

You may optionally order the results by any field that is returned by the API.

The parameters that configure this are as follows:

  • _orderby: Orders the results by in the specified field name. Results will be ordered in ascending order by default.
  • _order: May be used in conjunction with the _orderby option to set order to be ascending (asc) or descending (desc)..

For example:

curl "https://sheetlabs.com/ACME/getDomain?_orderby=domain&_order=desc"

You may also randomise the order of the results using the parameter _random=1. For example:

curl "https://sheetlabs.com/ACME/getDomain?_random=1"

Sheetlabs record identifier

You may see a field named __id returned in your API response. This is the internal Sheetlabs record identifier. If you plan on editing or deleting records via an API call, you will need to use this identifier. If not, then it can be ignored.

Coupon codes

One use case for Sheetlabs is to store a table of coupon codes (also known as voucher codes) and to provide an API that would allow for a single coupon to be fetched at a time, with guarantees that a coupon will only ever be returned once. If the API you are using is returning coupon codes then you should be aware of the following:

  • You are guaranteed to only be returned a coupon code once.
  • If the coupons have all been consumed, then you will get an empty response.