0
# RestNavigator
1
2
RestNavigator is a Python library for interacting with hypermedia APIs following REST level 3 patterns, specifically designed for HAL+JSON (Hypertext Application Language) APIs. It enables developers to navigate REST APIs by following links rather than hardcoding URLs, supporting features like templated links, authentication, embedded documents, and automatic identity mapping.
3
4
## Package Information
5
6
- **Package Name**: restnavigator
7
- **Language**: Python
8
- **Installation**: `pip install restnavigator`
9
10
## Core Imports
11
12
```python
13
from restnavigator import Navigator
14
```
15
16
For exception handling:
17
18
```python
19
from restnavigator.exc import HALNavigatorError, OffTheRailsException, UnexpectedlyNotJSON
20
```
21
22
For advanced utilities:
23
24
```python
25
from restnavigator.utils import CurieDict, LinkList, fix_scheme
26
```
27
28
## Basic Usage
29
30
```python
31
from restnavigator import Navigator
32
33
# Create a HAL navigator for an API
34
api = Navigator.hal('https://api.example.com/', default_curie='ex')
35
36
# Navigate the API using links
37
users = api['users'] # Follow the 'users' link
38
user = users['user'](id='123') # Follow templated 'user' link with parameters
39
40
# Fetch resource state
41
user_data = user() # or user.fetch()
42
43
# Perform HTTP operations
44
new_user = users.create({'name': 'John', 'email': 'john@example.com'})
45
updated_user = user.patch({'email': 'newemail@example.com'})
46
user.delete()
47
```
48
49
## Architecture
50
51
RestNavigator uses a navigator pattern that treats HAL+JSON APIs as traversable hypermedia structures:
52
53
- **Navigator Factory**: Creates navigators for API roots with shared configuration
54
- **HALNavigator**: Main navigation class for following links and performing HTTP operations
55
- **PartialNavigator**: Handles templated links that require parameter expansion
56
- **Identity Map**: Automatically reuses navigator instances for the same resources
57
- **Session Management**: Built-in support for authentication, headers, and request customization
58
59
## Capabilities
60
61
### Core Navigation
62
63
Primary factory method for creating HAL API clients and the main navigation interface for following links, fetching resources, and performing HTTP operations.
64
65
```python { .api }
66
class Navigator:
67
@staticmethod
68
def hal(root: str, apiname: str = None, default_curie: str = None,
69
auth: tuple = None, headers: dict = None, session = None) -> 'HALNavigator'
70
```
71
72
```python { .api }
73
class HALNavigator:
74
def __call__(self, raise_exc: bool = True) -> dict
75
def fetch(self, raise_exc: bool = True) -> dict
76
def links(self) -> 'CurieDict'
77
def embedded(self) -> 'CurieDict'
78
def __getitem__(self, args) -> 'HALNavigator'
79
def __contains__(self, value: str) -> bool
80
def __iter__(self) -> 'HALNavigator'
81
def next(self) -> 'HALNavigator'
82
```
83
84
[Core Navigation](./navigation.md)
85
86
### HTTP Operations
87
88
Comprehensive HTTP method support for RESTful operations including GET, POST, PUT, PATCH, and DELETE with proper error handling and response management.
89
90
```python { .api }
91
class HALNavigator:
92
def create(self, body: dict = None, raise_exc: bool = True, headers: dict = None) -> 'OrphanHALNavigator'
93
def upsert(self, body: dict, raise_exc: bool = True, headers = False) -> 'OrphanHALNavigator'
94
def patch(self, body: dict, raise_exc: bool = True, headers = False) -> 'OrphanHALNavigator'
95
def delete(self, raise_exc: bool = True, headers: dict = None) -> 'OrphanHALNavigator'
96
```
97
98
[HTTP Operations](./http-operations.md)
99
100
### Templated Links
101
102
Support for HAL templated links with parameter expansion and URI template processing according to RFC 6570.
103
104
```python { .api }
105
class PartialNavigator:
106
def __call__(self, **kwargs) -> 'HALNavigator'
107
def expand_uri(self, **kwargs) -> str
108
def expand_link(self, **kwargs) -> 'Link'
109
@property
110
def variables(self) -> set
111
@property
112
def template_uri(self) -> str
113
```
114
115
[Templated Links](./templated-links.md)
116
117
### Authentication & Sessions
118
119
Built-in authentication support for various methods including Basic Auth, OAuth2, and custom authentication schemes through requests session integration.
120
121
```python { .api }
122
class HALNavigator:
123
def authenticate(self, auth) -> None
124
@property
125
def session(self) -> 'Session'
126
@property
127
def headers(self) -> dict
128
```
129
130
[Authentication & Sessions](./authentication.md)
131
132
### Exception Handling
133
134
Comprehensive exception hierarchy for handling HTTP errors, parsing failures, and navigation issues with detailed error information.
135
136
```python { .api }
137
class HALNavigatorError(Exception):
138
def __init__(self, message: str, nav: 'HALNavigator', response)
139
@property
140
def status(self) -> int
141
```
142
143
[Exception Handling](./exceptions.md)
144
145
### Utility Functions
146
147
Enhanced collections and helper functions for HAL processing including CURIE support, link disambiguation, and data manipulation.
148
149
```python { .api }
150
class CurieDict(dict):
151
def __init__(self, default_curie: str = None)
152
153
class LinkList(list):
154
def get_by(self, prop: str, val, raise_exc: bool = False)
155
def named(self, name: str)
156
```
157
158
[Utilities](./utilities.md)
159
160
## Types
161
162
```python { .api }
163
class Link:
164
def __init__(self, uri: str, props: dict = None)
165
@property
166
def uri(self) -> str
167
@property
168
def props(self) -> dict
169
def relative_uri(self, root: str) -> str
170
171
class OrphanHALNavigator(HALNavigator):
172
@property
173
def parent(self) -> 'HALNavigator'
174
def __call__(self) -> dict
175
```
176
177
## Constants
178
179
```python { .api }
180
# HTTP Method Constants
181
GET = 'GET'
182
POST = 'POST'
183
DELETE = 'DELETE'
184
PATCH = 'PATCH'
185
PUT = 'PUT'
186
187
# Default Headers
188
DEFAULT_HEADERS = {
189
'Accept': 'application/hal+json,application/json',
190
'User-Agent': 'HALNavigator/{version}'
191
}
192
```