0
# API Root Management
1

2
API root operations for managing collections, checking capabilities, and retrieving status information within a specific TAXII API root. An API root represents a logical grouping of TAXII services and collections within a TAXII server.
3

4
## Capabilities
5

6
### API Root Connection
7

8
Connect to a specific TAXII API root endpoint with authentication and configuration options.
9

10
```python { .api }
11
class ApiRoot:
12
    def __init__(self, url, conn=None, user=None, password=None, verify=True,
13
                 proxies=None, auth=None, cert=None):
14
        """
15
        Create a TAXII API root endpoint connection.
16
        
17
        Parameters:
18
        - url (str): URL of TAXII API root endpoint
19
        - conn (_HTTPConnection, optional): Reuse existing connection
20
        - user (str, optional): Username for HTTP basic authentication
21
        - password (str, optional): Password for HTTP basic authentication
22
        - verify (bool): Validate SSL certificates (default: True)
23
        - proxies (dict, optional): HTTP/HTTPS proxy settings
24
        - auth (requests.auth.AuthBase, optional): Custom authentication object
25
        - cert (str or tuple, optional): SSL client certificate path or (cert, key) tuple
26
        """
27
```
28

29
### API Root Information
30

31
Access API root metadata including title, description, supported versions, and content limitations.
32

33
```python { .api }
34
@property
35
def title(self) -> str:
36
    """API root title (required)."""
37

38
@property
39
def description(self) -> str:
40
    """API root description (optional)."""
41

42
@property
43
def versions(self) -> list[str]:
44
    """List of supported TAXII versions (required)."""
45

46
@property
47
def max_content_length(self) -> int:
48
    """Maximum content length in bytes for requests (required)."""
49

50
@property
51
def custom_properties(self) -> dict:
52
    """Custom API root properties not defined in TAXII spec."""
53

54
@property
55
def _raw(self) -> dict:
56
    """Raw API root information response (parsed JSON)."""
57
```
58

59
### Collection Management
60

61
Access and manage collections within the API root.
62

63
```python { .api }
64
@property
65
def collections(self) -> list[Collection]:
66
    """List of Collection instances available in this API root."""
67
```
68

69
### API Root Operations
70

71
Refresh API root information and manage collections.
72

73
```python { .api }
74
def refresh(self, accept=None) -> None:
75
    """
76
    Update API root information and list of collections.
77
    
78
    Parameters:
79
    - accept (str, optional): Media type for Accept header
80
    """
81

82
def refresh_information(self, accept=None) -> None:
83
    """
84
    Update only the API root properties (not collections).
85
    
86
    Parameters:
87
    - accept (str, optional): Media type for Accept header
88
    """
89

90
def refresh_collections(self, accept=None) -> None:
91
    """
92
    Update only the list of collections (not API root info).
93
    
94
    Parameters:
95
    - accept (str, optional): Media type for Accept header
96
    """
97

98
def get_status(self, status_id, accept=None) -> Status:
99
    """
100
    Retrieve status information for an asynchronous operation.
101
    
102
    Parameters:
103
    - status_id (str): Status identifier from previous operation
104
    - accept (str, optional): Media type for Accept header
105
    
106
    Returns:
107
    Status: Status object with operation details
108
    """
109

110
def close(self) -> None:
111
    """Close the API root connection."""
112

113
def __enter__(self):
114
    """Context manager entry."""
115

116
def __exit__(self, exc_type, exc_val, exc_tb):
117
    """Context manager exit."""
118
```
119

120
## Usage Examples
121

122
### Basic API Root Access
123

124
```python
125
from taxii2client import Server
126

127
# Get API root from server
128
server = Server("https://taxii-server.example.com/taxii2/")
129
api_root = server.default or server.api_roots[0]
130

131
print(f"API Root: {api_root.title}")
132
print(f"Description: {api_root.description}")
133
print(f"Supported versions: {', '.join(api_root.versions)}")
134
print(f"Max content length: {api_root.max_content_length} bytes")
135
```
136

137
### Direct API Root Connection
138

139
```python
140
from taxii2client import ApiRoot
141

142
# Connect directly to specific API root
143
api_root = ApiRoot(
144
    url="https://taxii-server.example.com/taxii2/api1/",
145
    user="username",
146
    password="password"
147
)
148

149
# Access API root information
150
print(f"Title: {api_root.title}")
151
print(f"Versions: {api_root.versions}")
152
```
153

154
### Working with Collections
155

156
```python
157
# List all collections in API root
158
print(f"Collections ({len(api_root.collections)}):")
159
for collection in api_root.collections:
160
    print(f"  - {collection.title} (ID: {collection.id})")
161
    print(f"    Can Read: {collection.can_read}")
162
    print(f"    Can Write: {collection.can_write}")
163
    print(f"    Media Types: {', '.join(collection.media_types)}")
164

165
# Find collection by ID
166
target_id = "malware-indicators"
167
collection = next(
168
    (c for c in api_root.collections if c.id == target_id), 
169
    None
170
)
171
if collection:
172
    print(f"Found collection: {collection.title}")
173
else:
174
    print(f"Collection '{target_id}' not found")
175

176
# Find collections by capability
177
readable_collections = [c for c in api_root.collections if c.can_read]
178
writable_collections = [c for c in api_root.collections if c.can_write]
179

180
print(f"Readable collections: {len(readable_collections)}")
181
print(f"Writable collections: {len(writable_collections)}")
182
```
183

184
### Status Monitoring
185

186
```python
187
# Monitor status of previous operation
188
status_id = "status-12345-abcde"
189
status = api_root.get_status(status_id)
190

191
print(f"Status ID: {status.id}")
192
print(f"Status: {status.status}")
193
print(f"Total: {status.total_count}")
194
print(f"Success: {status.success_count}")
195
print(f"Failures: {status.failure_count}")
196
print(f"Pending: {status.pending_count}")
197

198
# Check if operation completed successfully
199
if status:  # Uses __bool__ method
200
    print("Operation completed successfully")
201
else:
202
    print(f"Operation not complete: {status.status}")
203
```
204

205
### Refreshing Information
206

207
```python
208
# Refresh all information
209
api_root.refresh()
210

211
# Refresh only API root info (faster)
212
api_root.refresh_information()
213

214
# Refresh only collections (useful if collections change frequently)
215
api_root.refresh_collections()
216

217
# Check for new collections after refresh
218
print(f"Collections after refresh: {len(api_root.collections)}")
219
```
220

221
### Context Manager Usage
222

223
```python
224
# Automatically handle connection cleanup
225
api_root_url = "https://taxii-server.example.com/taxii2/api1/"
226
with ApiRoot(api_root_url, user="user", password="pass") as api_root:
227
    print(f"Connected to: {api_root.title}")
228
    for collection in api_root.collections:
229
        print(f"Collection: {collection.title}")
230
    # Connection automatically closed when exiting context
231
```
232

233
### Custom Properties and Raw Data
234

235
```python
236
# Access custom properties not in TAXII spec
237
if api_root.custom_properties:
238
    print("Custom properties:")
239
    for key, value in api_root.custom_properties.items():
240
        print(f"  {key}: {value}")
241

242
# Access raw JSON response
243
raw_data = api_root._raw
244
print(f"Raw response keys: {list(raw_data.keys())}")
245
```