Introduction

The KPN SD-LAN SD-WAN Network View API offers an interface for software to interact directly with the KPN SD-LAN SD-WAN products, based on the Cisco Meraki cloud platform and Cisco Meraki managed devices. The API contains a set of endpoints for use cases such as monitoring, event management, and video camera analystics.

The API resources follow a structure like in the image below. Organizations consist of networks, which contain devices such as access points, switches and MX security appliances. The characteristics of these devices can be configured with the API.

Meraki Dashboard overview

The KPN SD-LAN SD-WAN Network View API is a REST API using HTTPS requests to a URL and JSON as a human-readable format.

The API call volume rate is limited to 3 calls per second per organization.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/kpn/meraki


Conceptual model

Conceptual model

Description

  1. You communicate the item of your ICT environment you want more info about to My API Store through the SD-LAN SD-WAN Network View API.
  2. My API Store immediately moves the request to the Cisco Meraki cloud platform.
  3. The Meraki controller retrieves the information from your ICT environment.
  4. The cloud platform returns the information you requested via the API to you.


Network View API

The Network View API gives users read rights to retrieve information from the Network View API resources.

Allowed methods: GET


Requirements

This API is only available for customers of KPN SD-LAN SD-WAN services based on Cisco Meraki.


Definitions

Layer 3 (L3) firewall rule

L3 firewall rules provide administrators granular access control of client traffic. Layer 3 firewalls filter traffic, based on the TCP/IP stack. This approach is sometimes also referred to as packet filtering because you’re essentially allowing and blocking individual network packets depending on where they originated and which ports they want to talk to.

MAC address

In a local area network (LAN) or other network, the MAC (Media Access Control) address is the computer's unique hardware number.

MX

Cisco Meraki MX Security Appliances are multi-functional security & SD-WAN enterprise appliances, with a wide set of capabilities to address multiple use cases from an all-in-one device.

PoE

Power over Ethernet (PoE) is a technology for wired Ethernet local area networks (LANs) that allows the electrical current necessary for the operation of each device to be carried by the data cables rather than by power cords.

Quality of Service (QoS)

QoS is the description or measurement of the overall performance of a service, such as a telephony, computer network or a cloud computing service, particularly the performance seen by the users of the network.

SSID

Service Set Identifier. A “service set” refers to a collection of wireless networking devices with the same parameters. SSIDs serve as "wireless network names" and are typically natural language labels.

Switch

A network switch is a device that connects different network segments together transparently.

Switch port

A network switch port is a physical interface on the switch where devices connect to the switch.

VLAN

A VLAN (virtual LAN) is a sub-network, which can group together collections of devices on separate physical local area networks (LANs).


API workflow

SD-LAN SD-WAN Network View


Features

  • Retrieve information about the configuration of your networks, devices, VLANs, and more.
  • Get the latest network status and information on events.
  • See results of the analytics performed on images captured with your security cameras.


Getting started

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.


How to...


Parameters marked with an asterisk are required. Example: serial*.

Retrieve Layer 3 firewall rules for MX appliances

This endpoint returns the L3 firewall rules for an MX appliance.

Request

GET /networks/{networkId}/l3FirewallRules

Path parameter Type Description
networkId* string Network identity is a portion of the TCP/IP address that is used to identify individuals or devices on a network such as a local area network or the Internet.

Response

^^Response example^^
Successful HTTP Status: 200
[
  {
    "comment": "Allow TCP traffic to subnet with HTTP servers.",
    "policy": "allow",
    "protocol": "tcp",
    "destPort": 443,
    "destCidr": "192.168.1.0/24",
    "srcPort": "Any",
    "srcCidr": "Any",
    "syslogEnabled": false
  }
]

Retrieve a list of switch ports

Lists the switch ports for a switch.

Request

GET /devices/{serial}/switchPorts

Path parameter Type Description
serial* string The serial number of the device. Example: Q7QN-9J8L-SGTD
Query parameter Type Description
t0 string The beginning of the timespan for the data. The maximum lookback period is 31 days from today.
timespan integer The timespan for which the information will be fetched. If specifying timespan, do not specify parameter t0. The value must be in seconds and be less than or equal to 31 days. The default is 1 day.

Response

^^Response example^^
Successful HTTP Status: 200
[
    {
        "number": 1,
        "name": "My switch port",
        "tags": "tag1 tag2",
        "enabled": true,
        "poeEnabled": true,
        "type": "access",
        "vlan": 10,
        "voiceVlan": 20,
        "isolationEnabled": false,
        "rstpEnabled": true,
        "stpGuard": "disabled",
        "accessPolicyNumber": "1234",
        "linkNegotiation": "Auto negotiate",
        "portScheduleId": "1234",
        "udld": "Alert only",
        "macWhitelist": [
            "34:56:fe:ce:8e:a0",
            "34:56:fe:ce:8e:a1"
        ],
        "stickyMacWhitelist": [
            "34:56:fe:ce:8e:b0",
            "34:56:fe:ce:8e:b1"
        ],
        "stickyMacWhitelistLimit": 5,
        "stormControlEnabled": true
    }
]

Retrieve a specific switch port

Request

GET /devices/{serial}/switchPorts/{number}

Path parameter Type Description
serial* string The serial number of the device. Example: Q7QN-9J8L-SGTD
number* string The number of the device. Example: Q7QN-9J8L-SGTD

Response

^^Response example^^
Successful HTTP Status: 200
{
    "number": 1,
    "name": "My switch port",
    "tags": "tag1 tag2",
    "enabled": true,
    "poeEnabled": true,
    "type": "access",
    "vlan": 10,
    "voiceVlan": 20,
    "isolationEnabled": false,
    "rstpEnabled": true,
    "stpGuard": "disabled",
    "accessPolicyNumber": "1234",
    "linkNegotiation": "Auto negotiate",
    "portScheduleId": "1234",
    "udld": "Alert only",
    "macWhitelist": [
        "34:56:fe:ce:8e:a0",
        "34:56:fe:ce:8e:a1"
    ],
    "stickyMacWhitelist": [
        "34:56:fe:ce:8e:b0",
        "34:56:fe:ce:8e:b1"
    ],
    "stickyMacWhitelistLimit": 5,
    "stormControlEnabled": true
}

Retrieve a list of Service Set Identifiers (SSID)

Lists the SSIDs in a network. Supports networks with access points or wireless-enabled security appliances and teleworker gateways.

Request

GET /networks/{networkId}/ssids

Path parameter Type Description
networkId* string The network ID of the device. Example: L_1234567894811040791

Response

^^Response example^^
Successful HTTP Status: 200
[
    {
        "number": 0,
        "name": "My SSID",
        "enabled": true,
        "splashPage": "Click-through splash page",
        "ssidAdminAccessible": false,
        "authMode": "8021x-radius",
        "encryptionMode": "wpa-eap",
        "wpaEncryptionMode": "WPA2 only",
        "radiusServers": [
            {
                "host": "0.0.0.0",
                "port": 3000
            }
        ],
        "radiusAccountingEnabled": false,
        "radiusEnabled": true,
        "radiusAttributeForGroupPolicies": "Filter-Id",
        "radiusFailoverPolicy": "null",
        "radiusLoadBalancingPolicy": "null",
        "ipAssignmentMode": "NAT mode",
        "adminSplashUrl": "http://example.com",
        "splashTimeout": "30 minutes",
        "walledGardenEnabled": true,
        "walledGardenRanges": "example.com",
        "minBitrate": 11,
        "bandSelection": "5 GHz band only",
        "perClientBandwidthLimitUp": 0,
        "perClientBandwidthLimitDown": 0,
        "visible": true,
        "availableOnAllAps": false,
        "availabilityTags": [ "test-tag" ]
    }
]

Retrieve a single SSID

Returns a specific Service Set Identifier (SSID).

Request

GET /networks/{networkId}/ssids/{number}

Path parameter Type Description
networkId* string The network ID of the device. Example: L_1234567894811040791
number* string The number of the SSID instance.

Response

^^Response example^^
Successful HTTP Status: 200
{
    "number": 0,
    "name": "My SSID",
    "enabled": true,
    "splashPage": "Click-through splash page",
    "ssidAdminAccessible": false,
    "authMode": "8021x-radius",
    "encryptionMode": "wpa-eap",
    "wpaEncryptionMode": "WPA2 only",
    "radiusServers": [
        {
            "host": "0.0.0.0",
            "port": 3000
        }
    ],
    "radiusAccountingEnabled": false,
    "radiusEnabled": true,
    "radiusAttributeForGroupPolicies": "Filter-Id",
    "radiusFailoverPolicy": "null",
    "radiusLoadBalancingPolicy": "null",
    "ipAssignmentMode": "NAT mode",
    "adminSplashUrl": "http://example.com",
    "splashTimeout": "30 minutes",
    "walledGardenEnabled": true,
    "walledGardenRanges": "example.com",
    "minBitrate": 11,
    "bandSelection": "5 GHz band only",
    "perClientBandwidthLimitUp": 0,
    "perClientBandwidthLimitDown": 0,
    "visible": true,
    "availableOnAllAps": false,
    "availabilityTags": [ "test-tag" ]
}


List of API resources

Go to the interactive OpenAPI Specification (OAS) documentation on SwaggerHub to explore the SD-LAN SD-WAN Network View API endpoints. See KPN SD-LAN SD-WAN Network View API.

Each endpoint has a complete description of all the required parameters:

  • Bluetooth clients.
  • Bluetooth settings.
  • Camera quality retention profiles.
  • Cameras.
  • Clients.
  • Connectivity monitoring destinations.
  • Content filtering categories.
  • Content filtering rules.
  • Devices.
  • Events.
  • Firewalled services.
  • Floorplans.
  • Group policies.
  • HTTP servers.
  • Intrusion settings.
  • Link aggregations.
  • MG Cellular Gateway.
  • MR Wireless Network.
  • MX Appliances.
  • Malware settings.
  • Management interface settings.
  • Meraki auth users.
  • Named tag scope.
  • NetFlow settings.
  • Networks.
  • Organization.
  • Radio settings.
  • SNMP settings.
  • SSIDs.
  • Security events.
  • Splash login attempts.
  • Splash settings.
  • Switch ACLs.
  • Switch port schedules.
  • Switch ports.
  • Switch profiles.
  • Switch settings.
  • Switch stacks.
  • Traffic shaping.
  • Uplink settings.
  • VLANs.
  • Wireless settings.


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a website tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting code from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback