Query Parameters

Optional query parameters apply to the retrieval of all resources. These include:

To add a parameter to an API endpoint, precede the parameter with a question mark ?. For example:

https://example-library.edu/iii/sierra-api/v6/bibs?limit=20

To add multiple parameters to a URL, precede the first parameter with a question mark and each additional parameter with an ampersand &. For example:

https://example-library.edu/iii/sierra-api/v6/bibs?id=1000002,1000004&field=fixedFields

Search Parameters

You can specify certain record properties in order to return only records that contain the corresponding data.

Specifies the property and property value required to qualify for inclusion in the result set.

The Interactive Documentation lists all valid parameters for each API endpoint.

Deleted Records

Deleted records return only their id, deletedDate, and deleted properties.

For item records, you can submit the duedate parameter without a value to return items that have any due date.

Examples:

To return multiple bibs or items, specify the id property and a comma-delimited list of record numbers (without the record type tag):

https://example-library.edu/iii/sierra-api/v6/items?id=1234567,4567890,8675309

Returns items with IDs i1234567, i4567890, i8675309. The number of IDs cannot exceed the maximum record limit or the system returns an error.

To return items based on the associated bib ID, specify the bibIds property and a comma-delimited list of bibliographic record IDs (without the record type tag or check digit):

https://example-library.edu/iii/sierra-api/v6/items?bibIds=7654321,7654320,7654319

Returns the first x items, where x = the default record limit, linked to at least one of the bib records b7654321, b7654320, or b7654319.

To return bibs that were updated within a specific time frame, specify the "updatedDate" property and a date range:

https://example-library.edu/iii/sierra-api/v6/bibs?updatedDate=[2013-09-03T13:17:45Z,2013-09-03T13:37:45Z]

Returns the first x bibs, where x = the default record limit, with an update date that falls from 1:17:45 p.m. 9/3/13 UTC (inclusive) and 1:37:45 p.m. 9/3/13 UTC (inclusive).

To return only items that have a due date, specify the duedate parameter without a date value:

https://example-library.edu/iii/sierra-api/v6/items?duedate

Returns the first x item objects that have a duedate, where x = the default record limit.

Range Syntax

Range syntax applies to dates and record IDs.

Range syntax has the form:

[<startValue>,<endValue>]

The start and end values are inclusive.

You can specify ranges in the following ways:

Exactly (a search parameter)

updatedDate=2013-12-10T17:16:35Z

id=1000004

From <startValue> to <endValue> (inclusive)

updatedDate=[2013-12-10T17:16:35Z,2013-12-13T21:34:35Z]

id=[1000004,1000054]

<startValue> and after (inclusive)

updatedDate=[2013-12-10T17:16:35Z,]

id=[1000004,]

Up to and including <endValue>

updatedDate=[,2013-12-13T21:34:35Z]

id=[,1000054]

Dates must match the date format of the property to be retrieved. In most cases, the format is ISO 8601 combined date and time in UTC with Z (zero) offset. Some date properties, such as catalogDate and deletedDate, are date only, with no time. Refer to the bib object and item object descriptions and examples for more information.

Filter Parameters

You can specify which properties (fields) to return for records that satisfy the search parameters.

fields=<field1,field2,field3>

Specifies the field(s) to return; no other properties or components. For example:

https://example-library.edu/iii/sierra-api/v6/bibs?fields=id

Returns the first x bib IDs, where x = the default record limit.

To specify multiple fields, separate the fields with a comma:

https://example-library.edu/iii/sierra-api/v6/bibs?fields=id,createdDate,suppressed

Returns just the IDs, created date, and suppression status of the first x bibs, where x = the default record limit.

The fields parameter returns object properties. It does not apply to the individual contents of the fixedFields object or varFields array.

Default Response Contents

Default query responses do not include all data for all record types. You must specify additional properties and lists using filter parameters. For example:

https://example-library.edu/iii/sierra-api/v6/bibs/1000002?fields=fixedFields,varFields

Returns the id property, fixedFields object, and varFields array for a single bibliographic record.

When you use the fields parameter, the API returns only the ID and specified properties. You can specify the value default to retrieve all default properties in addition to any explicitly specified properties, such as fixedFields. For example:

https://example-library.edu/iii/sierra-api/v6/bibs/1000002?fields=default,fixedFields,varFields

Returns the default properties plus the fixedFields object and varFields array for a single bibliographic record.

Pagination Parameters

You can specify a limited range of the full result set.

All queries return the first objects found, up to the default limit, unless you specify pagination parameters.

limit=<x>

Specifies the maximum number of results. For example:

https://example-library.edu/iii/sierra-api/v6/bibs?limit=20

Returns the first 20 bibs.

The current default limit on the Sierra API Developer's Sandbox is "50". The system maximum limit is "2000".

offset=<x>

Specifies the beginning record (zero-indexed) of the result set returned. For example:

https://example-library.edu/iii/sierra-api/v6/bibs?limit=10&offset=50

Returns the 50th through 59th bibs.

When you specify an offset, multi-record responses begin with information indicating the total number of results and the starting position of the current page of results. For example:

"total": 120,
"start": 50,

API Performance and the "offset" Parameter

When you use the offset parameter, the system must calculate the total number of results. This calculation is resource-intensive and can negatively affect performance. That is, queries that include the offset parameter return results much more slowly than those without the parameter.

The preferred, more efficient method of harvesting data is to use open ID ranges, such as id=[<recID>,]. For example:

/bibs?id=[<recID>,]

To harvest all nondeleted records:

Generate the appropriate URL to get each result page.
1. Start with id=0. The system returns all records, up to the default limit of 50 records:
/bibs?id=[0,]&deleted=false
1. Extract the last record ID from the list of entries. The following JSON path returns the last record ID in the entries list:
$.entries[-1:].id
1. Add "1" to the last record ID to ensure that you get the next available record ID, whether or not the specified ID exists:
/bibs?id=[<last_record_ID_from_page + 1>,]&deleted=false
Loop until the system returns a page with fewer than 50 results.

Presentation Parameters

You can specify a list of acceptable human languages for the API response using the Accept-Language header in your request. The default is en-US.

The available languages depend on the configuration of the library's Sierra system.

Refer to the Header Field Definitions prescribed by the World Wide Web Consortium (W3C) for more information on the Accept-Language header.