@boundlessdigital/meraki-sdk

Boundless Meraki SDK for Node.js or Browser

This package allows you to interact with the Meraki Dashboard API from a Javascript application (Node or Browser).

If using it from a browser, you must point the host to an API Gateway that supports CORS, such as the Boundless API Gateway.

Uses Axios client behind.

Installation

Depending on which package manager you use, install this package by running the following:

• Yarn: yarn add @boundlessdigital/meraki-sdk
• NPM: npm install --save @boundlessdigital/meraki-sdk

Once installed, you can use it in your application by instantiating the client, configuring your API Key, and then calling the API methods on the client directly.

Client Usage

To create a client instance, use:

import { Client } from '@boundlessdigital/meraki-sdk';
const client = new Client({ /* options */ });

Available client options

Key	Type	Default Value	Description
api_key	string	Env variable for api_key_env_var key	Meraki API Key to authenticate requests. Can be explicitly specified or autodetected from environment
api_key_env_var	string	"MERAKI_DASHBOARD_API_KEY"	Environment variable name to seach for API Key when api_key option is not provided
base_url	string	"https://api.meraki.com"	Backend endpoint where requests will be sent to. Can be changed to point to the API Gateway or CloudFront
base_path	string	"/api/v1"	API base path. Can be changed to confugure custom API Gateway or CloudFront routes
user_agent	string	"Boundless/1.0 Boundless"	HTTP User Agent used for requests
timeout	number	60000	HTTP timeout in milliseconds
request_mode	"dispatch" | "preview" | "batch"	"dispatch"	Current request mode of a client. Learn more on that below
retry_on_error	boolean	true	Tries to repeat the request on error if true. HTTP errors will not trigger this by default
retry_on_statuses	number[]	[429, 503]	HTTP response statuses that should be considered as errors ans trigger a retry mechanism
maximum_retries	number	5	Maximum amount of retries before the request rejection (when retry_on_error is true)
proxy	string	null	Is not used now
retry_on_rate_limit	boolean	false	Is not used now
output_log	boolean	false	Is not used now
print_to_console	boolean	false	Is not used now
action_batch_retry_wait_time	number	0	Is not used now

Request Modes

There are three available request modes: dispatch, preview, and batch.

The default mode is dispatch, which immediately dispatches requests to the Meraki endpoint (as any common API client does).

However, the client makes it possible to use the Meraki Action Batch feature by preparing and executing the batches once the work has been batched; the preview and batch modes control that process.

The preview mode does nothing but return the action body that can then be added to the batch actions array. This is useful to manage actions and batches or for debugging purposes.

The batch mode prepares and adds the action body to the current batch actions list.

The following methods can be used to change the request mode: client.set_request_mode(/* mode */), client.set_dispatch_mode(), client.set_preview_mode(), client.set_batch_mode().

Actions Batches, Types Safety

There is a limited amount of Meraki API methods that support Action Batches. All the GET methods are not supported by default, but the complete list can be found using import { batchable_actions } from '@boundlessdigital/meraki-sdk'.

TBD (not implemented yet)

API Spec and Resources

Besides the Client implementation, there are a raw API spec and a few pre-processed resources to help build request bodies, work with Action Batches, etc. It can be accessed by

import {
    spec,
    schemas,
    endpoints,
    operations,
    batchable_actions,
    unbatchable_actions,
    operations_builder,
} from '@boundlessdigital/meraki-sdk'

The available resources are:

• spec - a complete raw OpenAPI Definition of the Meraki API
• schemas - pre-processed OpenAPI Definition, a dictionary of all the data types used in the Meraki API
• endpoints - pre-processed OpenAPI Definition, a complete list of HTTP endpoints with their definitions as an array
• operations - pre-processed OpenAPI Definition to help find operation definition by its ID (operation ID is the dictionary key, operation body is the value)
• batchable_actions - a dictionary of all the API operations that support Action Batches. OpenAPI Operation ID is the dictionary key here.
• unbatchable_actions - a list of the API operations that are supposed to support Action Batches but actually do not (because of bad Meraki API design or other reasons)
• operations_builder - a dictionary of available API resources (in a form they are presented in the Client autogenerated code), where each resource contains available operations over it (like read, create, update, delete etc.)