or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdexceptions.mdhttp-operations.mdindex.mdnavigation.mdtemplated-links.mdutilities.md
tile.json

tessl/pypi-restnavigator

A python library for interacting with HAL+JSON APIs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/restnavigator@1.0.x

To install, run

npx @tessl/cli install tessl/pypi-restnavigator@1.0.0

index.mddocs/

RestNavigator

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.

Package Information

  • Package Name: restnavigator
  • Language: Python
  • Installation: pip install restnavigator

Core Imports

from restnavigator import Navigator

For exception handling:

from restnavigator.exc import HALNavigatorError, OffTheRailsException, UnexpectedlyNotJSON

For advanced utilities:

from restnavigator.utils import CurieDict, LinkList, fix_scheme

Basic Usage

from restnavigator import Navigator

# Create a HAL navigator for an API
api = Navigator.hal('https://api.example.com/', default_curie='ex')

# Navigate the API using links
users = api['users']  # Follow the 'users' link
user = users['user'](id='123')  # Follow templated 'user' link with parameters

# Fetch resource state
user_data = user()  # or user.fetch()

# Perform HTTP operations
new_user = users.create({'name': 'John', 'email': 'john@example.com'})
updated_user = user.patch({'email': 'newemail@example.com'})
user.delete()

Architecture

RestNavigator uses a navigator pattern that treats HAL+JSON APIs as traversable hypermedia structures:

  • Navigator Factory: Creates navigators for API roots with shared configuration
  • HALNavigator: Main navigation class for following links and performing HTTP operations
  • PartialNavigator: Handles templated links that require parameter expansion
  • Identity Map: Automatically reuses navigator instances for the same resources
  • Session Management: Built-in support for authentication, headers, and request customization

Capabilities

Core Navigation

Primary factory method for creating HAL API clients and the main navigation interface for following links, fetching resources, and performing HTTP operations.

class Navigator:
    @staticmethod
    def hal(root: str, apiname: str = None, default_curie: str = None, 
            auth: tuple = None, headers: dict = None, session = None) -> 'HALNavigator'
class HALNavigator:
    def __call__(self, raise_exc: bool = True) -> dict
    def fetch(self, raise_exc: bool = True) -> dict
    def links(self) -> 'CurieDict'
    def embedded(self) -> 'CurieDict'
    def __getitem__(self, args) -> 'HALNavigator'
    def __contains__(self, value: str) -> bool
    def __iter__(self) -> 'HALNavigator'
    def next(self) -> 'HALNavigator'

Core Navigation

HTTP Operations

Comprehensive HTTP method support for RESTful operations including GET, POST, PUT, PATCH, and DELETE with proper error handling and response management.

class HALNavigator:
    def create(self, body: dict = None, raise_exc: bool = True, headers: dict = None) -> 'OrphanHALNavigator'
    def upsert(self, body: dict, raise_exc: bool = True, headers = False) -> 'OrphanHALNavigator'
    def patch(self, body: dict, raise_exc: bool = True, headers = False) -> 'OrphanHALNavigator'
    def delete(self, raise_exc: bool = True, headers: dict = None) -> 'OrphanHALNavigator'

HTTP Operations

Templated Links

Support for HAL templated links with parameter expansion and URI template processing according to RFC 6570.

class PartialNavigator:
    def __call__(self, **kwargs) -> 'HALNavigator'
    def expand_uri(self, **kwargs) -> str
    def expand_link(self, **kwargs) -> 'Link'
    @property
    def variables(self) -> set
    @property
    def template_uri(self) -> str

Templated Links

Authentication & Sessions

Built-in authentication support for various methods including Basic Auth, OAuth2, and custom authentication schemes through requests session integration.

class HALNavigator:
    def authenticate(self, auth) -> None
    @property
    def session(self) -> 'Session'
    @property
    def headers(self) -> dict

Authentication & Sessions

Exception Handling

Comprehensive exception hierarchy for handling HTTP errors, parsing failures, and navigation issues with detailed error information.

class HALNavigatorError(Exception):
    def __init__(self, message: str, nav: 'HALNavigator', response)
    @property
    def status(self) -> int

Exception Handling

Utility Functions

Enhanced collections and helper functions for HAL processing including CURIE support, link disambiguation, and data manipulation.

class CurieDict(dict):
    def __init__(self, default_curie: str = None)

class LinkList(list):
    def get_by(self, prop: str, val, raise_exc: bool = False)
    def named(self, name: str)

Utilities

Types

class Link:
    def __init__(self, uri: str, props: dict = None)
    @property
    def uri(self) -> str
    @property
    def props(self) -> dict
    def relative_uri(self, root: str) -> str

class OrphanHALNavigator(HALNavigator):
    @property
    def parent(self) -> 'HALNavigator'
    def __call__(self) -> dict

Constants

# HTTP Method Constants
GET = 'GET'
POST = 'POST'
DELETE = 'DELETE'
PATCH = 'PATCH'
PUT = 'PUT'

# Default Headers
DEFAULT_HEADERS = {
    'Accept': 'application/hal+json,application/json',
    'User-Agent': 'HALNavigator/{version}'
}