Update work/tbx/meraki_api.md

work/tbx/meraki_api.md

@@ -1,3 +1,114 @@
+Cisco Meraki organizes its networks and devices in a hierarchical structure that provides a clear and scalable way to manage and monitor your network infrastructure. Understanding this hierarchy is essential for effectively using the Meraki Dashboard and API. Here’s a breakdown of the hierarchy:
+
+## Meraki Hierarchy
+
+1. **Organizations**
+2. **Networks**
+3. **Devices**
+4. **Clients**
+
+### 1. Organizations
+
+**Organizations** are the top-level entities in the Meraki ecosystem. An organization can represent a company, a business unit, or a large geographical area. Each organization can contain multiple networks.
+
+- **Key Attributes:**
+  - `id`: Unique identifier for the organization.
+  - `name`: Name of the organization.
+
+**Example API Request:**
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/organizations" | jq .
+```
+
+### 2. Networks
+
+**Networks** are collections of devices and configurations that work together to provide network services. Networks can be configured for different purposes such as office locations, retail stores, or different sites within a campus.
+
+- **Key Attributes:**
+  - `id`: Unique identifier for the network.
+  - `organizationId`: ID of the organization to which the network belongs.
+  - `name`: Name of the network.
+  - `type`: Type of network (e.g., `wireless`, `switch`, `appliance`, `combined`).
+
+**Example API Request:**
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/organizations/ORGANIZATION_ID/networks" | jq .
+```
+
+### 3. Devices
+
+**Devices** are the individual hardware units that make up a network. This includes wireless access points, switches, security appliances, cameras, and other Meraki devices.
+
+- **Key Attributes:**
+  - `serial`: Unique serial number of the device.
+  - `networkId`: ID of the network to which the device belongs.
+  - `model`: Model of the device (e.g., `MX64`, `MR33`).
+  - `name`: Name of the device.
+  - `mac`: MAC address of the device.
+
+**Example API Request:**
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/networks/NETWORK_ID/devices" | jq .
+```
+
+### 4. Clients
+
+**Clients** are the end devices that connect to the Meraki network. This can include computers, smartphones, tablets, and IoT devices.
+
+- **Key Attributes:**
+  - `id`: Unique identifier for the client.
+  - `description`: Description of the client.
+  - `mac`: MAC address of the client.
+  - `ip`: IP address assigned to the client.
+  - `usage`: Data usage statistics for the client.
+
+**Example API Request:**
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/networks/NETWORK_ID/clients" | jq .
+```
+
+## Practical Usage Example
+
+Here’s how you can traverse this hierarchy using the Meraki Dashboard API:
+
+### Step 1: List Organizations
+
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/organizations" | jq .
+```
+
+### Step 2: List Networks in an Organization
+
+Replace `ORGANIZATION_ID` with the actual ID of your organization.
+
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/organizations/ORGANIZATION_ID/networks" | jq .
+```
+
+### Step 3: List Devices in a Network
+
+Replace `NETWORK_ID` with the actual ID of your network.
+
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/networks/NETWORK_ID/devices" | jq .
+```
+
+### Step 4: List Clients in a Network
+
+Replace `NETWORK_ID` with the actual ID of your network.
+
+```sh
+curl -s -H "X-Cisco-Meraki-API-Key: YOUR_API_KEY" "https://api.meraki.com/api/v1/networks/NETWORK_ID/clients" | jq .
+```
+
+## Conclusion
+
+Understanding the hierarchy used by Meraki to organize networks and devices is crucial for effective network management and monitoring. The Meraki Dashboard API provides a powerful way to programmatically interact with your network infrastructure, allowing you to automate tasks, gather data, and perform complex queries.
+
+By practicing with the Meraki Dashboard API and using `jq` to parse and manipulate the JSON data, you can gain deeper insights into your network and improve your overall management capabilities. If you have any further questions or need additional examples, feel free to ask!
+
+---
+
 Great! Let's explore some freely available JSON data sources on the web that you can use to practice `jq`, and then we can touch on how to use the Meraki Dashboard API.
 
 ## Free JSON Data Sources