Skip to content

Commit ce03ce9

Browse files
phate999phate999
authored
Update README.md
1 parent 2543734 commit ce03ce9

1 file changed

Lines changed: 112 additions & 67 deletions

File tree

‎ncm/README.md‎

Lines changed: 112 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,112 @@
1-
# Cradlepoint NCM SDK
2-
This is a Python client library for Cradlepoint NCM API (both v2 and v3)
3-
4-
INSTALL AND RUN INSTRUCTIONS
5-
6-
1. Install the ncm pip package, or copy the ncm.py file into your working directory:
7-
```
8-
pip3 install ncm
9-
```
10-
11-
2. Set NCM API v2 Keys. API Keys must be passed as a dictionary:
12-
```
13-
api_keys = {
14-
'X-CP-API-ID': 'aaaa',
15-
'X-CP-API-KEY': 'bbbb',
16-
'X-ECM-API-ID': 'cccc',
17-
'X-ECM-API-KEY': 'dddd'
18-
}
19-
```
20-
For API v3 Key it can be included in the same dictionary as token (optional):
21-
```
22-
api_keys = {
23-
'X-CP-API-ID': 'aaaa',
24-
'X-CP-API-KEY': 'bbbb',
25-
'X-ECM-API-ID': 'cccc',
26-
'X-ECM-API-KEY': 'dddd',
27-
"token": 'eeee'
28-
}
29-
```
30-
Note: if only using v3, just include the token in the dictionary.
31-
32-
3. Import the module and create an instance of the NcmClient object:
33-
34-
If using pip:
35-
```
36-
from ncm import ncm
37-
n = ncm.NcmClient(api_keys=api_keys)
38-
```
39-
40-
If not using pip:
41-
```
42-
import ncm
43-
n = ncm.NcmClient(api_keys=api_keys)
44-
```
45-
46-
4. Call functions from the module as needed. For example:
47-
```
48-
print(n.get_accounts())
49-
```
50-
51-
USAGE AND TIPS:
52-
53-
This python class includes a few optimizations to make it easier to work with the API.
54-
The default record limit is set at 500 instead of the Cradlepoint default of 20,
55-
which reduces the number of API calls required to return large sets of data.
56-
57-
This can be modified by specifying a "limit parameter":
58-
```
59-
n.get_accounts(limit=10)
60-
```
61-
You can also return the full list of records in a single array without the need for paging
62-
by passing limit='all':
63-
```
64-
n.get_accounts(limit='all')
65-
```
66-
It also has native support for handling any number of "__in" filters beyond Cradlepoint's limit of 100.
67-
The script automatically chunks the list into groups of 100 and combines the results into a single array.
1+
# NCM API Client Documentation
2+
3+
## Overview
4+
5+
This module provides easy access to the Cradlepoint NCM API with support for both v2 and v3 APIs. It includes a singleton pattern for simple usage and module-level function access for convenience.
6+
7+
## Requirements
8+
9+
Cradlepoint NCM API Keys are required to make API calls:
10+
- **For v2 API**: X-CP-API-ID, X-CP-API-KEY, X-ECM-API-ID, X-ECM-API-KEY
11+
- **For v3 API**: Bearer token
12+
13+
## Usage Options
14+
15+
### 1. Zero-Configuration Usage (Recommended)
16+
17+
```python
18+
import ncm
19+
20+
# Set these environment variables once:
21+
# export X_CP_API_ID="b89a24a3"
22+
# export X_CP_API_KEY="4b1d77fe271241b1cfafab993ef0891d"
23+
# export X_ECM_API_ID="c71b3e68-33f5-4e69-9853-14989700f204"
24+
# export X_ECM_API_KEY="f1ca6cd41f326c00e23322795c063068274caa30"
25+
# export NCM_API_TOKEN="your-bearer-token" # For v3 API
26+
27+
# Then just use it - no setup required!
28+
accounts = ncm.get_accounts()
29+
devices = ncm.get_devices()
30+
routers = ncm.get_routers()
31+
```
32+
33+
### 2. Explicit Configuration (Alternative)
34+
35+
```python
36+
import ncm
37+
38+
# Option A: Set up API keys explicitly
39+
api_keys = {
40+
'X-CP-API-ID': 'b89a24a3',
41+
'X-CP-API-KEY': '4b1d77fe271241b1cfafab993ef0891d',
42+
'X-ECM-API-ID': 'c71b3e68-33f5-4e69-9853-14989700f204',
43+
'X-ECM-API-KEY': 'f1ca6cd41f326c00e23322795c063068274caa30'
44+
}
45+
ncm.set_api_keys(api_keys)
46+
47+
# Option B: Manual environment variable loading
48+
ncm.set_api_keys() # Manually loads from environment
49+
```
50+
51+
### 3. Traditional Class Instantiation
52+
53+
```python
54+
import ncm
55+
api_keys = {...} # Same as above
56+
client = ncm.NcmClient(api_keys=api_keys)
57+
accounts = client.get_accounts()
58+
```
59+
60+
### 4. Mixed v2/v3 API Usage
61+
62+
```python
63+
import ncm
64+
api_keys = {
65+
'X-CP-API-ID': 'b89a24a3',
66+
'X-CP-API-KEY': '4b1d77fe271241b1cfafab993ef0891d',
67+
'X-ECM-API-ID': 'c71b3e68-33f5-4e69-9853-14989700f204',
68+
'X-ECM-API-KEY': 'f1ca6cd41f326c00e23322795c063068274caa30',
69+
'token': 'your-v3-bearer-token' # For v3 API
70+
}
71+
client = ncm.NcmClient(api_keys=api_keys)
72+
# Methods will automatically route to the appropriate API version
73+
```
74+
75+
### 5. Backward Compatibility (Legacy Scripts)
76+
77+
```python
78+
from ncm import ncm # Old import pattern still works!
79+
80+
api_keys = {
81+
'X-ECM-API-ID': os.environ.get("X_ECM_API_ID"),
82+
'X-ECM-API-KEY': os.environ.get("X_ECM_API_KEY"),
83+
'X-CP-API-ID': os.environ.get("X_CP_API_ID"),
84+
'X-CP-API-KEY': os.environ.get("X_CP_API_KEY"),
85+
'Authorization': f'Bearer {os.environ.get("TOKEN")}'
86+
}
87+
88+
# All existing patterns work unchanged:
89+
ncm_client = ncm.NcmClientv3(api_key=token, log_events=True)
90+
ncm_client.set_api_keys(api_keys) # Instance method still works
91+
92+
# New convenience pattern also available:
93+
ncm.set_api_keys(api_keys) # Module-level method
94+
routers = ncm.get_routers() # Direct method access
95+
```
96+
97+
## Features
98+
99+
- ✅ Zero-configuration usage with automatic environment variable loading
100+
- ✅ Singleton pattern for easy module-level access
101+
- ✅ Automatic API version routing (v3 prioritized over v2)
102+
- ✅ Module-level function access (`ncm.method_name()`)
103+
- ✅ Automatic initialization on import if environment variables are set
104+
- ✅ Full backward compatibility with existing scripts
105+
- ✅ Support for both import patterns: `"import ncm"` and `"from ncm import ncm"`
106+
- ✅ Optimized pagination (default limit 500 vs API default 20)
107+
- ✅ Support for `limit='all'` to get all records without paging
108+
- ✅ Automatic chunking of `"__in"` filters beyond 100 item limit
109+
110+
## Documentation
111+
112+
Full documentation of the Cradlepoint NCM API is available at: [https://developer.cradlepoint.com](https://developer.cradlepoint.com)

0 commit comments

Comments
 (0)