Meta Fields
These are not processed as query (filtering) constraints, but they affect the output.
_body=false
Return an empty body in the response. Useful for large payloads that you don't need to see again (like file contents). Note this is a network optimization; the result is calculated as normal, just not included in the response.
.../emails/531429/?_body=false
returns an empty body, but does have an accurate etag in the header.
_expand
Which of the fields to expand in the result. Will ignore incorrectly named fields or fields that aren't endpoints.
.../emails/531429/
returns:
{
"href": "http://127.0.0.1:8080/api/v1/emails/531429/",
"person": "http://127.0.0.1:8080/api/v1/people/10000658/",
"address": "developer@nols.edu",
"created_at": "2013-06-27T17:11:04Z",
"created_by": "ehervol",
"note": "",
"status": "Current",
"updated_at": "2013-06-27T17:11:04Z",
"updated_by": "ehervol",
"verified_at": null
}
.../emails/531429/?_expand=person
returns:
{
"href": "http://127.0.0.1:9999/api/v1/emails/531429/",
"person": {
"href": "http://127.0.0.1:9999/api/v1/people/10000658/",
"counts": "http://127.0.0.1:9999/api/v1/people/10000658/counts/",
"addresses": "http://127.0.0.1:9999/api/v1/people/10000658/addresses/",
"all_names": "http://127.0.0.1:9999/api/v1/people/10000658/names/",
"birth_date": "1965-03-15",
"citizenship": "United States",
"citizenship2": "",
"classifications": "http://127.0.0.1:9999/api/v1/people/10000658/classifications/",
"created_at": "1993-03-20T08:54:40Z",
"created_by": "unknown",
"dup_check_date": "2009-04-27",
"emails": "http://127.0.0.1:9999/api/v1/people/10000658/emails/",
"ethnic_origin": "White",
"event_logs": "http://127.0.0.1:9999/api/v1/people/10000658/event-logs/",
"exp_work_agreements": "http://127.0.0.1:9999/api/v1/people/10000658/exp-work-agreements/",
"gender": "Male",
"name": "Eric C. Hervol",
"name_first": "Eric",
"name_last": "Hervol",
"name_middle": "Charles",
"name_preferred": "Eric",
"name_prefix": "Mr",
"name_suffix": "",
"notification_message": "",
"phones": "http://127.0.0.1:9999/api/v1/people/10000658/phones/",
"relationships": "http://127.0.0.1:9999/api/v1/people/10000658/relationships/",
"reservations": "http://127.0.0.1:9999/api/v1/people/10000658/reservations/",
"search_first": "ERIC",
"search_last": "HERVOL",
"search_preferred": "ERIC",
"sounds_like_last": "H614",
"type": "Individual",
"updated_at": "2017-06-01T09:34:15Z",
"updated_by": "synchtool"
},
"address": "developer@nols.edu",
"created_at": "2013-06-27T17:11:04Z",
"created_by": "ehervol",
"is_current": true,
"note": "",
"updated_at": "2013-06-27T17:11:04Z",
"updated_by": "ehervol"
}
You can also expand endpoints of endpoints recursively like so:
.../emails/531429/?_expand=person.exp_work_agreements.course.evaluations
returns:
{
"href": "http://127.0.0.1:9999/api/v1/emails/531429/",
"person": {
"href": "http://127.0.0.1:9999/api/v1/people/10000658/",
"counts": "http://127.0.0.1:9999/api/v1/people/10000658/counts/",
"addresses": "http://127.0.0.1:9999/api/v1/people/10000658/addresses/",
"all_names": "http://127.0.0.1:9999/api/v1/people/10000658/names/",
"all_notification_messages": "http://127.0.0.1:9999/api/v1/people/10000658/notification-messages/",
"birth_date": "1965-03-15",
"certifications": "http://127.0.0.1:9999/api/v1/people/10000658/certifications/",
"citizenship": "United States",
"citizenship2": "",
"classifications": "http://127.0.0.1:9999/api/v1/people/10000658/classifications/",
"created_at": "1993-03-20T08:54:40Z",
"created_by": "unknown",
"dup_check_date": "2009-04-27",
"emails": "http://127.0.0.1:9999/api/v1/people/10000658/emails/",
"ethnic_origin": "White",
"event_logs": "http://127.0.0.1:9999/api/v1/people/10000658/event-logs/",
"exp_applications": "http://127.0.0.1:9999/api/v1/people/10000658/exp-applications/",
"applications": "http://127.0.0.1:9999/api/v1/people/10000658/exp-applications/",
"exp_work_agreements": [
{
"href": "http://127.0.0.1:9999/api/v1/exp-work-agreements/28339/",
"course": {
"href": "http://127.0.0.1:9999/api/v1/courses/expedition/39004154/",
"ao_assigned": "rdavis",
"code": "FSB",
"created_at": "1997-07-09T21:36:25Z",
"created_by": "",
"days_until_start": 0,
"end_date": "1998-12-01",
<snip>
"work_agreements": "http://127.0.0.1:9999/api/v1/courses/expedition/39004154/work-agreements/",
"course_type": "Semester",
"deposit": 0,
"deposit_due_days_after": 0,
"equipment_deposit": 400.0,
"evaluations": [],
<snip>
},
"course_name": "FSB-09/15/1998",
"person": "http://127.0.0.1:9999/api/v1/people/10000658/",
<snip>
"section": "Sailing",
"start_date": "1998-11-10",
"status": "Completed",
"status_date": "1998-12-03",
<snip>
You can see that each nested resource in turn has been expanded (even evaluations, it just happens to be empty). WITH GREAT POWER COMES GREAT RESPONSIBILITY. Deeply nested queries through the nols-api are not efficient and can put a huge load on the server - don't be a jerk.
_fields
Restricts the results to just the fields listed. Will ignore incorrectly named fields.
.../courses/?query=code=acs&_fields=href,name,end_date
will return those three fields for ACS courses instead of the normal 40+ fields.
You can combine _expand and _field options to reduce the clutter in nested queries. Modifying the previous _expand example
.../emails/531429/?_expand=person.exp_work_agreements.course&_fields=address,person.name,person.exp_work_agreements.course.name
returns:
{
"person": {
"exp_work_agreements": [
{
"course": {
"name": "FSB-09/15/1998"
}
},
<snip>
{
"course": {
"name": "SSR-3-02/22/1989"
}
},
{
"course": {
"name": "ROPE-01/01/1960"
}
}
],
"name": "Eric C. Hervol"
},
"address": "developer@nols.edu"
}
_format
Specify the format of the result: current values are xml, json, pdf and xlsx. Not all formats apply to all endpoints.
.../people/10000658/?_format=xml
returns:
<root>
<href>
http://127.0.0.1:8080/api/v1/people/10000658/?_format=xml
</href>
<birth_date>1965-03-15</birth_date>
<classifications>
http://127.0.0.1:8080/api/v1/people/10000658/classifications/?_format=xml
</classifications>
<created_at>1993-03-20T08:54:40Z</created_at>
<created_by>unknown</created_by>
<emails>
http://127.0.0.1:8080/api/v1/people/10000658/emails/?_format=xml
</emails>
<event_logs>
http://127.0.0.1:8080/api/v1/people/10000658/event-logs/?_format=xml
</event_logs>
<gender>M</gender>
<name>Eric C. Hervol</name>
<name_first>Eric</name_first>
<name_last>Hervol</name_last>
<name_middle>Charles</name_middle>
<name_preferred>Eric</name_preferred>
<name_prefix>Mr</name_prefix>
<name_suffix/>
<type>Individual</type>
<updated_at>2016-06-18T09:37:53Z</updated_at>
</root>
You can bypass the _format representation with .xml, .json, .pdf and .xlsx extensions, but they won't work with query strings.
.../people/10000658.xml
.../people/10000658/?_format=xml
are equivalent.
_limit
Turn on pagination and set the number of items per page for list resources.
.../people/?query=search_last=smith&_fields=name&_limit=3
Displays 3 items per page.
{
"count": 3722,
"next": "http://127.0.0.1:8080/api/v1/people/?_fields=name&_limit=3&_offset=3&query=search_last=smith",
"previous": null,
"results": [
{
"name": "LARRY SMITH"
},
{
"name": "LINDA SMITH"
},
{
"name": "AJ Smith"
}
]
}
Every page result displays a total count, and next and previous links if they exist. The default limit is 50 if not specified and the maximum limit is 10,000.
_offset
Turn on pagination and set the starting item for the current page. Offsets are zero-based: _offset=7 will display the 8th item at the top of the page. Default offset is 0 if not specified.
.../people/?query=search_last=smith&_fields=name&_limit=3&_offset=6
{
"count": 3722,
"next": "http://127.0.0.1:8080/api/v1/people/?_fields=name&_limit=3&_offset=9&query=search_last=smith",
"previous": "http://127.0.0.1:8080/api/v1/people/?_fields=name&_limit=3&_offset=3&query=search_last=smith",
"results": [
{
"name": "Aaron Smith"
},
{
"name": "Aaron J. Smith"
},
{
"name": "Aaron Smith"
}
]
}
You can specify an offset that is out of bounds:
.../people/?query=search_last=smith&_fields=name&_offset=3790
and you'll just get an empty result:
{
"count": 3722,
"next": null,
"previous": "http://127.0.0.1:8080/api/v1/people/?_fields=name&_limit=50&_offset=3740&query=search_last=smith",
"results": []
}
If neither _limit nor _offset is specified, pagination is off.
_max_items
Set the maximum number of items returned by a query. Will return an error if actual query results exceed the value set. Results are not paged and will ignore any values set for _limit or _offset.
.../people/?query=search_last=smith&_max_items=500
This is intended for efficient retrieval of small results of open-ended queries. A user might submit a query that unintentionally returns huge results. This is intended to return quickly with the message the query needs to be more specific.
_order
Sort the results in a specific order. Generally sorting should be done on the client side, but with pagination the sorting needs to take place before pagination. _order takes a comma separated list of field names. Descending order is indicated by a leading '-'.
.../people/?query=search_last=smith&_fields=name,birth_date&_limit=3&_order=birth_date
{
"count": 3804,
"next": "http://127.0.0.1:9999/api/v1/people/?_fields=name%2Cbirth_date&_limit=3&_offset=3&_order=birth_date&query=search_last=smith",
"previous": null,
"results": [
{
"birth_date": "1924-06-29",
"name": "Clyde N. Smith"
},
{
"birth_date": "1927-10-04",
"name": "Kenneth Smith"
},
{
"birth_date": "1933-11-15",
"name": "JoAnn E. Smith"
}
]
}
.../people/?query=search_last=smith&_fields=name,birth_date&_limit=3&_order=-birth_date,name_middle
{
"count": 3804,
"next": "http://127.0.0.1:9999/api/v1/people/?_fields=name%2Cbirth_date&_limit=3&_offset=3&_order=-birth_date%2Cname_middle&query=search_last%3Dsmith",
"previous": null,
"results": [
{
"birth_date": null,
"name": "Connie A. Smith"
},
{
"birth_date": null,
"name": "James A. Smith"
},
{
"birth_date": null,
"name": "John A. Smith"
}
]
}
Sorting always happens, whether specified explicitly or not. To disable sorting entirely specify _order=none. This can increase speed for very large (more than 50,000) results. The disadvantage being result order is non-deterministic, so eTag values may differ for the same set of results.