General filters

General filters can be applied to most resources.

Limits

limit: Limit number of items returned.

To search for the first entry in a resource:

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" “https://192.168.0.122/api/v1/localusers/?format=json&limit=1”

The URL requires additional quoting in this case otherwise the Unix CLI treats the “&” as a instruction to place the cURL command into the background.

Response

< HTTP/1.1 200 OK

< Date: Tue, 10 Jun 2014 09:43:33 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< X-Frame-Options: SAMEORIGIN

< Content-Language: en

< Cache-Control: no-cache

< Transfer-Encoding: chunked

< Content-Type: application/json

<

* Connection #0 to host 192.168.0.122 left intact

* Closing connection #0

{"meta": {"limit": 1, "next": "/api/v1/localusers/?offset=1&limit=1&format=json", "offset": 0, "previous": null, "total_count": 3}, "objects": [{"address": "", "city": "", "country": "", "custom1": "", "custom2": "", "custom3": "", "email": "", "first_name": "", "id": 5, "last_name": "", "mobile_number": "", "phone_number": "", "resource_uri": "/api/v1/localusers/5/", "state": "", "token_auth": false, "token_serial": "", "token_type": null, "user_groups": ["/api/v1/usergroups/9/", "/api/v1/usergroups/8/"], "username": "test_user2"}]}

Only the first user in the list is returned. Note that this excludes admin users which are never returned by this query hence the reason why this user ID is > 5.

Offset

offset: Specify an offset for the returned items (zero-based). E.g. if there are 10 items, to return item #5 - #10 only, specify offset=4:

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" “https://192.168.0.122/api/v1/localusers/?format=json&offset=4”

Order

order_by: Order returned list by a known field name (e.g. ?order_by=<field name>):

curl -k -v -u "admin:zeyDZXmP6GbKcerqdWWEYNTnH2TaOCz5HTp2dAVS" “https://192.168.0.122/api/v1/localusers/?format=json&order_by=username”

Response

< HTTP/1.1 200 OK

< Date: Tue, 10 Jun 2014 16:41:23 GMT

< Server: Apache

< Vary: Accept,Accept-Language,Cookie

< X-Frame-Options: SAMEORIGIN

< Content-Language: en

< Cache-Control: no-cache

< Transfer-Encoding: chunked

< Content-Type: application/json

<

{"meta": {"limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 3}, "objects": [{"address": "", "city": "", "country": "", "custom1": "", "custom2": "", "custom3": "", "email": "", "first_name": "", "id": 4, "last_name": "", "mobile_number": "", "phone_number": "", "resource_uri": "/api/v1/localusers/4/", "state": "", "token_auth": false, "token_serial": "", "token_type": null, "user_groups": ["/api/v1/usergroups/8/"], "username": "test_user"}, {"address": "", "city": "", "country": "GB", "custom1": "example", "custom2": "", "custom3": "", "email": "", "first_name": "", "id": 5, "last_name": "", "mobile_number": "", "phone_number": "", "resource_uri": "/api/v1/localusers/5/", "state": "", "token_auth": false, "token_serial": "", "token_type": null, "user_groups": ["/api/v1/usergroups/9/", "/api/v1/usergroups/8/"], "username": "test_user2"}, {"address": "", "city": "", "country": "GB", "custom1": "example", "custom2": "", "custom3": "", "email": "test_user3@example.com", "first_name": "", "id": 6, "last_name": "", "mobile_number": "", "phone_number": "", "resource_uri": "/api/v1/localusers/6/", "state": "", "token_auth": false, "token_serial": "", "token_type": null, "user_groups": [], "username": "test_user3"}]}

Filter lookup expressions

Expression	Description
exact	Search for an exact match (e.g. name__exact=John Doe, would return user with name "John Doe", but not "john doe")
iexact	Search for a case-insensitive exact match (e.g. name__iexact=john doe, would return user with name "John Doe")
contains	Search for an item that contains a specific keyword
icontains	Same as above, but case-insensitive
in	Search for items that matches specific filter criteria (e.g. to return items that has a name matching "John" or "Bill", ?name__in=John&name__in=Bill)
startswith	Search for items that starts with a text
istartswith	Same as above, but case-insensitive