Plugins & Endpoints

Plugins are adapters that parse API specification files into normalized endpoint definitions. The generated code gives you typed constants with IDE autocomplete.

How It Works

source file → Plugin.parse() → list[EndpointSpec] → generate() → endpoints.py

1. A plugin adapter reads a source file (RBAC JSON, OpenAPI, custom format)
2. It returns a list of EndpointSpec objects with path, methods, name, description
3. The code generator writes a Python module with frozen Endpoint constants

Built-in Plugins

Plugin	Source Format	Description
snf-instance-rest	rbac_access_matrix.json	SFM Redfish API endpoints

EndpointSpec

The intermediate format produced by plugin adapters:

@dataclass
class EndpointSpec:
    path: str                    # "/redfish/v1/SFM/1/BlueprintTemplates"
    methods: tuple[str, ...]     # ("GET", "POST")
    name: str                    # "BlueprintTemplates"
    description: str = ""        # Human-readable description
    metadata: dict = field(...)  # Plugin-specific extra data

Endpoint (runtime)

The frozen constant imported in user code:

@dataclass(frozen=True)
class Endpoint:
    path: str
    methods: tuple[str, ...]

Generated Code

After restful plugin load, the generated endpoints.py looks like:

# Auto-generated by restful (snf-instance-rest) — 42 endpoints
from restful.models import Endpoint

BlueprintTemplates = Endpoint(
    path="/redfish/v1/SFM/1/BlueprintTemplates",
    methods=("GET",),
)

Infrastructures = Endpoint(
    path="/redfish/v1/SFM/1/Infrastructures",
    methods=("GET", "POST"),
)

Using Endpoints

from apis.my_api.endpoints import BlueprintTemplates, Infrastructures

response = client.get(BlueprintTemplates)
response = client.post(Infrastructures, payload={"Name": "my-infra"})