IN BETA: Filters for popular devices endpoints ๐Ÿ“๐Ÿ’ช๐Ÿผโ˜•

John-K
Meraki Employee

IN BETA: Filters for popular devices endpoints ๐Ÿ“๐Ÿ’ช๐Ÿผโ˜•

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:

 

 

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:

EndpointsResponse parametersPartial match query parametersExact 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.

4 REPLIES 4
Inderdeep
Kind of a big deal

@John-K : thanks for the update !

Regards
Inderdeep Singh
www.thenetworkdna.com ( Awarded by Cisco IT Blogs award 2020)
PhilipDAth
Kind of a big deal

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.

Thanks for this feedback!

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

Get notified when there are additional replies to this discussion.
Welcome to the Meraki Community!
To start contributing, simply sign in with your Cisco account. If you don't yet have a Cisco account, you can sign up.