Query Operators

Query Operators

An Ed-Fi REST API should support searching capabilities with the possible use of selectors, paging, and views. These are discussed below.

Search

An Ed-Fi REST API should support querying capabilities when searching a collection of Resources. Query operators are applied to the query string using the following format: {collectionURI}?{propertyName}{operator}{value}. Currently, the equals operator is the only operator specified. Other operators (>, <, ‘like’, ‘and’, ‘or’, etc.) may be implemented.

Table 4. Equals Operator, the Only Operator Specified for Searching a Collection of Resources

For example, to search all available Students having the first name “John” as an exact match, a {propertyName}={value} formulation is used (as shown above):

https://api.example.com/v1/students?firstName=john

Selectors

Selectors allow application developers to be more selective about how much data is returned in the resource representations. Implementation of selectors in an Ed-Fi REST API is optional.

Table 5. Selectors Allow Increased Selectivity in the Data that is Returned

For example, to retrieve only a Student’s first and last names:

https://api.example.com/v1/students/{id}?fields=firstName,lastSurname

To retrieve everything except a Student’s middle name:

https://api.example.com/v1/students/{id}?excludeFields=middleName

Paging

Paging is a mechanism that restricts the number of results returned by an operation. Paging is a recommended feature. When multiple records are being returned, the total count of all records should be returned as an additional data member of the response body. The limit parameter may be used in the query string to set the maximum number of records returned. If no value is supplied, the limit parameter should default to 25. The offset parameter may be set to specify how many records to skip when getting the result set. The default value for offset should default to 0. 

For example, to get the first name and last name of a collection of available Students from positions 31 to 40:

https://api.example.com/v1/students?fields=firstName,lastSurname&limit=10&offset=30

Views

Views are a recommended feature. Views provide the ability for a client to request predefined and/or custom views be returned as a resource.

For example, a view could include student information, assessments, attendance records, gradebook entries, and transcript information.