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
```