IN BETA: Filters for popular devices endpoints 📁💪🏼☕

[John_on_API]

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.

[Inderdeep]

@John_on_API : thanks for the update !

[PhilipDAth]

Good innovation.

This has got to be one of the most common bits of code I have in all my projects:

	# Search for the org
	orgs = meraki.organizations.get_organizations()
	for org in orgs:
		if org['name'] == orgName:
			orgId=org['id']
			break;

 Oh how I wish I could filter on the name of an org so I can just get the ID.  Ditto for getting the ID of a network.

[John_on_API]

Thanks for this feedback!

[Greenberet]

I know we've discussed this already a few times, but since you are now adding filters =D

getOrganizations?apienabled=True/False to filter out all organizations with enabled or disabled api access =D