From ffa34c61332d0ec5db918e29ccd029a63a9f28d9 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Tue, 7 May 2019 14:23:02 -0400 Subject: [PATCH] Updated documentation --- CHANGELOG.md | 2 ++ docs/api/overview.md | 23 +++++++++++++++++++++-- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b2b7ee83..36ab646f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -186,6 +186,7 @@ functionality provided by the front end UI. * [#2791](https://github.com/digitalocean/netbox/issues/2791) - Add `comments` field for tags * [#2920](https://github.com/digitalocean/netbox/issues/2920) - Rename Interface `form_factor` to `type` (backward-compatible until v2.7) * [#2926](https://github.com/digitalocean/netbox/issues/2926) - Add change logging to the Tag model +* [#3038](https://github.com/digitalocean/netbox/issues/3038) - OR logic now used when multiple values of a query filter are passed ## API Changes @@ -193,6 +194,7 @@ functionality provided by the front end UI. * New API endpoint for custom field choices: `/api/extras/_custom_field_choices/` * ForeignKey fields now accept either the related object PK or a dictionary of attributes describing the related object. * Organizational objects now include child object counts. For example, the Role serializer includes `prefix_count` and `vlan_count`. +* Removed the `id__in` filter from all models. (Use `?id=1&id=2` format instead.) * Added a `description` field for all device components. * dcim.Device: The devices list endpoint now includes rendered context data. * dcim.DeviceType: `instance_count` has been renamed to `device_count`. diff --git a/docs/api/overview.md b/docs/api/overview.md index 6b9a1a429..e74a12371 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -274,12 +274,31 @@ A list of objects retrieved via the API can be filtered by passing one or more q GET /api/ipam/prefixes/?status=1 ``` -Certain filters can be included multiple times within a single request. These will effect a logical OR and return objects matching any of the given values. For example, the following will return all active and reserved prefixes: +The choices available for fixed choice fields such as `status` are exposed in the API under a special `_choices` endpoint for each NetBox app. For example, the available choices for `Prefix.status` are listed at `/api/ipam/_choices/` under the key `prefix:status`: ``` -GET /api/ipam/prefixes/?status=1&status=2 +"prefix:status": [ + { + "label": "Container", + "value": 0 + }, + { + "label": "Active", + "value": 1 + }, + { + "label": "Reserved", + "value": 2 + }, + { + "label": "Deprecated", + "value": 3 + } +], ``` +For most fields, when a filter is passed multiple times, objects matching _any_ of the provided values will be returned. For example, `GET /api/dcim/sites/?name=Foo&name=Bar` will return all sites named "Foo" _or_ "Bar". The exception to this rule is ManyToManyFields which may have multiple values assigned. Tags are the most common example of a ManyToManyField. For example, `GET /api/dcim/sites/?tag=foo&tag=bar` will return only sites tagged with both "foo" _and_ "bar". + ## Custom Fields To filter on a custom field, prepend `cf_` to the field name. For example, the following query will return only sites where a custom field named `foo` is equal to 123: