Generic REST API Adapter

Relevant source files

The following files were used as context for generating this wiki page:

• infrahub_sync/adapters/genericrestapi.py
• infrahub_sync/adapters/rest_api_client.py
• dev/guides/adding-an-adapter.md
• dev/guidelines/writing-an-adapter.md
• dev/knowledge/sync-architecture.md
• dev/knowledge/adapter-anatomy.md

The Generic REST API Adapter provides a configurable base class for connecting external systems to Infrahub via RESTful APIs. It reduces code duplication by offering flexible authentication, resource extraction, and object transformation logic. Developers subclass this adapter to support systems like ServiceNow, Infoblox, or internal IPAM tools without writing integration code from scratch.

Sources: infrahub_sync/adapters/genericrestapi.py:23-28, README.md

Architecture and Components

The adapter architecture relies on two primary classes: GenericrestapiAdapter and GenericrestapiModel. The adapter class manages the connection to the external API using a RestApiClient, while the model class handles the data structure of the synchronized objects.

Class Hierarchy

The following diagram illustrates the relationship between the generic REST adapter and the core diffsync and infrahub-sync mixins.

RestApiClient

The adapter uses a RestApiClient to handle HTTP communication. It supports multiple authentication methods including tokens, API keys, and basic authentication. It also manages SSL verification and request timeouts.

Sources: infrahub_sync/adapters/genericrestapi.py:47-105, infrahub_sync/adapters/rest_api_client.py

Configuration and Settings

The adapter is configured through the settings dictionary provided in the sync configuration. It prioritizes environment variables for sensitive credentials before falling back to static settings.

Authentication Configuration

The adapter supports several authentication strategies defined in the auth_method setting.

Setting Key	Description	Default
url	Base URL of the target API.	None
api_endpoint	Specific API path prefix.	/api/v0
auth_method	Strategy: token, x-auth-token, api-key, key, or basic.	token
timeout	Request timeout in seconds.	30
verify_ssl	Enables or disables SSL certificate verification.	True

Sources: infrahub_sync/adapters/genericrestapi.py:58-96

Environment Variable Resolution

The adapter attempts to resolve connection parameters from environment variables first to ensure security.

Data Loading Process

The model_loader method orchestrates the retrieval and processing of data. It performs four distinct phases: fetching, extraction, filtering/transformation, and loading into the diffsync store.

Loading Sequence

The following sequence diagram describes the data flow from the REST API into the internal store.

Object Transformation (obj_to_diffsync)

This method converts raw API dictionaries into a format compatible with DiffSyncModel.

1. Identity Derivation: It derives a local_id using derive_identifier_key.
2. Field Mapping: It iterates through mapping.fields to apply static values or map API keys to model attributes.
3. Reference Resolution: If a field is a reference, the adapter searches the store for the related object's unique_id.

Sources: infrahub_sync/adapters/genericrestapi.py:173-201

Implementation Example

When implementing a new adapter based on the generic REST base, you subclass GenericrestapiAdapter and override specific methods if the API behavior deviates from standard patterns.

from infrahub_sync.adapters.genericrestapi import GenericrestapiAdapter

class PeeringManagerAdapter(GenericrestapiAdapter):
    type = "PeeringManager"

    def __init__(self, *args, **kwargs):
        super().__init__(adapter_type="PeeringManager", *args, **kwargs)
        # Custom initialization or settings overrides

Sources: dev/guides/adding-an-adapter.md:32-35, dev/guidelines/writing-an-adapter.md:25-27

Summary

The Generic REST API Adapter serves as the foundational connector for REST-based systems within the infrahub-sync ecosystem. By centralizing common patterns for HTTP communication, authentication, and DiffSync model conversion, it allows developers to focus on schema mapping and system-specific logic rather than boilerplate integration code.