Let's talk about efficiency. Have you ever paged through a large data set, searching for a specific piece of information? With a sufficiently large deployment, it might feel like looking for a needle in a haystack. Which of my switches are offline? When were all my MT20s claimed? Which Meraki devices match a list of MAC addresses? You might call one of the following popular endpoints to get that information: getOrganizationDevices List the devices in an organization (devices) getOrganizationInventoryDevices Return the device inventory for an organization (inventory devices) getOrganizationDevicesStatuses List the status of every Meraki device in the organization (devices statuses) These endpoints are quite powerful, but if you have a huge number of devices in an organization, then you might have needed to get the entire data set before whittling it down to the specific devices relevant to your objective. That means extra bandwidth and API budget consumption, as well as more complex data filtering required in your API client. There were also several pieces of metadata that previously were only returned by a single endpoint, e.g. model, but that information is highly relevant to all of these endpoints. Today we're augmenting these endpoints (in beta) with a number of new response and query parameters that you can use to substantially streamline your consumption of these endpoints, and reduce complexity in your API client. The query parameters are filters that indicate additional criteria that you want to apply to a given dataset; dashboard then processes these and returns only those items that meet the criteria. Now in beta: filtering by query parameter Let's take these use cases as examples: Which of my switches are offline? Previously, you might: GET /organizations/{organizationId}/devices/statuses and then you would filter it client-side to the devices where status is offline. Now, you can instead: GET /organizations/{organizationId}/devices/statuses?statuses[]=offline&productTypes[]=switch and Dashboard will only return those switches that are offline. When were all my MT20s claimed? Previously, you might: GET/organizations/{organizationId}/inventoryDevices and then you would filter it client-side to the devices where status is offline. Now, you can instead: GET /organizations/{organizationId}/inventoryDevices?models[]=MT20 and Dashboard will only return information about MT20s in your organization. Which Meraki devices match a list of MAC addresses? Previously, you might: GET /organizations/{organizationId}/devices and then search the list for devices that matched the MAC address client-side. Now, if you want a partial MAC match, such as x:y, then you can instead: GET /organizations/{organizationId}/devices?mac=x:y Or, if you want one or more exact matches, you can instead: GET /organizations/{organizationId}/devices?macs[]=ab:cd:ef:01:23:45&macs[]=01:02:03:cd:ef:ab How does filtering work? Query parameters take two primary forms: Partial match These params are typically just singular nouns, like "mac" or "ip". They correspond to a response parameter and look for partial text matches. You can provide one argument for a given partial match query param. If you provide multiple, only the last one in the request URL will be processed. Exact match These params are plural nouns followed by square brackets, e.g. "macs[]" and "serials[]". They look for exact matches only. You can combine multiple instances of them to match mulitple criteria as shown above with an effective OR logic. When stringing different query params together, an AND logic is applied to the different query parameters. For example, this query: /organizations/:organizationId/devices?productTypes[]=sensor&productTypes[]=wireless&networkIds[]=L_id1&networkIds[]=L_id2&mac=9:8 applies the logic: (productType == sensor OR wireless) AND (networkId == L_id1 OR L_id2) AND (mac contains 9:8) As you can see, it's pretty powerful, especially if you have many thousands of devices in your organization. And yes: it supports tags. 🔖💪🏼❗ What filters are currently available in beta? Beta participants can leverage all of the following features today, in addition to the existing features: Endpoints Response parameters Partial match query parameters Exact match query parameters /devices, /devices/statuses, and /inventoryDevices serial mac model productType tags serials[] macs[] networkIds[] models[] tags[] tagFilterType /devices name serial mac /devices/statuses statuses[] How do I join the beta? If you'd like the join the beta, you can get started here. When will these features be generally available? The GA date is TBD but we look forward to sharing more information as we collect beta feedback.
... View more
