0
# Core Navigation
1
2
Core navigation functionality that provides the foundation for interacting with HAL+JSON APIs. These components enable link following, resource fetching, and hypermedia traversal.
3
4
## Capabilities
5
6
### Navigator Factory
7
8
Creates HAL navigator instances for API roots with shared configuration and session management.
9
10
```python { .api }
11
class Navigator:
12
@staticmethod
13
def hal(root: str, apiname: str = None, default_curie: str = None,
14
auth: tuple = None, headers: dict = None, session = None) -> 'HALNavigator':
15
"""
16
Create a HAL navigator for the given API root.
17
18
Parameters:
19
- root: API root URL (the only hardcoded URL in your application)
20
- apiname: Optional name for the API (used in navigator display)
21
- default_curie: Default CURIE prefix for link relations
22
- auth: Authentication credentials (tuple for basic auth)
23
- headers: Default headers to send with all requests
24
- session: Custom requests Session object for advanced authentication
25
26
Returns:
27
HALNavigator instance for the API root
28
"""
29
```
30
31
Usage example:
32
33
```python
34
from restnavigator import Navigator
35
36
# Basic usage
37
api = Navigator.hal('https://api.example.com/')
38
39
# With authentication and configuration
40
api = Navigator.hal(
41
'https://api.example.com/',
42
apiname='MyAPI',
43
default_curie='ex',
44
auth=('username', 'password'),
45
headers={'User-Agent': 'MyApp/1.0'}
46
)
47
48
# With OAuth2 session
49
from requests_oauthlib import OAuth2Session
50
oauth_session = OAuth2Session('client_id', token='access_token')
51
api = Navigator.hal('https://api.example.com/', session=oauth_session)
52
```
53
54
### Main Navigation Interface
55
56
The primary interface for navigating HAL APIs, following links, and accessing resource state.
57
58
```python { .api }
59
class HALNavigator:
60
def __call__(self, raise_exc: bool = True) -> dict:
61
"""
62
Fetch resource state or return cached state.
63
64
Parameters:
65
- raise_exc: Whether to raise exceptions on HTTP errors
66
67
Returns:
68
Resource state as dictionary
69
"""
70
71
def fetch(self, raise_exc: bool = True) -> dict:
72
"""
73
Perform GET request and return state, bypassing cache.
74
75
Parameters:
76
- raise_exc: Whether to raise exceptions on HTTP errors
77
78
Returns:
79
Fresh resource state from server
80
"""
81
82
def links(self) -> 'CurieDict':
83
"""
84
Returns dictionary of linked navigators by relation.
85
86
Returns:
87
CurieDict mapping link relations to HALNavigator instances
88
"""
89
90
def embedded(self) -> 'CurieDict':
91
"""
92
Returns dictionary of embedded navigators by relation.
93
94
Returns:
95
CurieDict mapping embedded relations to HALNavigator instances
96
"""
97
98
def __getitem__(self, args) -> 'HALNavigator':
99
"""
100
Navigate relationships using bracket notation.
101
102
Parameters:
103
- args: Link relation(s) to follow, supports chaining
104
105
Returns:
106
HALNavigator for the target resource
107
"""
108
109
def __contains__(self, value: str) -> bool:
110
"""
111
Check if link relation exists in links or embedded resources.
112
113
Parameters:
114
- value: Link relation to check for
115
116
Returns:
117
True if relation exists
118
"""
119
120
def __iter__(self) -> 'HALNavigator':
121
"""
122
Iterate through paginated resources using 'next' links.
123
124
Returns:
125
Iterator yielding HALNavigator instances
126
"""
127
128
def next(self) -> 'HALNavigator':
129
"""
130
Get next navigator in pagination sequence.
131
132
Returns:
133
HALNavigator for next page or None
134
"""
135
136
def docsfor(self, rel: str) -> None:
137
"""
138
Open documentation for link relation in browser.
139
140
Parameters:
141
- rel: Link relation to get documentation for
142
"""
143
```
144
145
### Properties
146
147
```python { .api }
148
class HALNavigator:
149
@property
150
def uri(self) -> str:
151
"""Current resource URI"""
152
153
@property
154
def apiname(self) -> str:
155
"""API name for display purposes"""
156
157
@property
158
def resolved(self) -> bool:
159
"""Whether resource has been fetched from server"""
160
161
@property
162
def status(self) -> tuple:
163
"""HTTP status code and reason phrase"""
164
165
@property
166
def state(self) -> dict:
167
"""Current resource state data"""
168
169
@property
170
def response(self):
171
"""HTTP response object from last request"""
172
173
@property
174
def title(self) -> str:
175
"""Title from self link properties"""
176
177
@property
178
def profile(self) -> str:
179
"""Profile from self link properties"""
180
181
@property
182
def type(self) -> str:
183
"""Type from self link properties"""
184
```
185
186
### Advanced Navigation Examples
187
188
```python
189
# Basic link following
190
users = api['users']
191
user = api['users']['user']
192
193
# Chained navigation with single bracket call
194
user = api['users', 'user']
195
196
# Navigation with list indexing
197
first_user = api['users', 0] # Get first item from users list
198
199
# Check if links exist
200
if 'posts' in user:
201
posts = user['posts']
202
203
# Pagination iteration
204
for page in api['posts']:
205
print("Processing page:", page.uri)
206
# Process page items
207
break # Prevent infinite iteration
208
209
# Working with embedded vs linked resources
210
api_links = api.links() # Only linked resources
211
api_embedded = api.embedded() # Only embedded resources
212
api['relation'] # Searches both links and embedded
213
```