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.)