RESTful API

The rXg provides two RESTful APIs for third-party integration. The Modern API at /api/ is the recommended interface for all new integrations, offering built-in pagination, rate limiting, and a browsable HTML interface. The legacy scaffold API at /admin/scaffolds/ remains available for backward compatibility.

Access to both APIs is controlled by the API key mechanism. Use the Admins page to set up API key access. It is good security practice to ensure that separate accounts (and hence, unique API keys) are used for each mechanism that will access the rXg via the RESTful API. Furthermore, each account and associated API key should be limited to the absolute minimum access rights needed to accomplish the desired tasks.

Legacy Scaffold API

Note: The documentation below describes the legacy scaffold API at /admin/scaffolds/. For new integrations, see the Modern API section.

The base URL for the legacy scaffold API follows the form:

https://DNS.record.for.rXg/admin/scaffolds/

The use of HTTPS is required. Thus it is necessary to ensure that a proper DNS record and SSL certificate is configured on the target rXg. Furthermore, it is important that the caller be able to correctly validate the installed SSL certificate.

The desired model must be appended to the base URL. The model describes the underlying database table that will be accessed. For example:

https://DNS.record.for.rXg/admin/scaffolds/accounts/

The models that are available for access via the RESTful API are described in the rXg API documentation.

The desired action must also be appended to the URL. For example:

https://DNS.record.for.rXg/admin/scaffolds/accounts/create/

The set of possible actions are create, show (or list), update and destroy. These correspond to the standard database CRUD semantics. The appropriate HTTP verb must be used in conjunction with the selected action.

| create | HTTP POST | | show | HTTP GET | | list | HTTP GET | | update | HTTP PUT | | destroy | HTTP DELETE |

There is an optional format parameter that may be appended to the URL. For example:

https://DNS.record.for.rXg/admin/scaffolds/accounts/index.html/
https://DNS.record.for.rXg/admin/scaffolds/accounts/index.xml/
https://DNS.record.for.rXg/admin/scaffolds/accounts/index.json/

Specifying the optional parameter changes the format for both the input and output presentation. For example, sending a HTTP GET to:

https://DNS.record.for.rXg/admin/scaffolds/accounts/index/3.html

Results in the following output:

<dl>
<dt>Login</dt>
<dd class="login-view"> cpatterson746 </dd>
<dt>First name</dt>
<dd class="first_name-view"> Colin </dd>
<dt>Last name</dt> <dd
class="last_name-view"> Patterson </dd>
<dt>Email</dt> <dd
class="email-view"> [email protected] </dd>
[unknown] </dd>

...

Use the XML format specification by sending sending a HTTP GET to:

https://DNS.record.for.rXg/admin/scaffolds/accounts/index/3.xml

Results in the following output:

<account>
    <bill-at type="datetime" nil="true"/>
    <created-at type="datetime">2012-05-10T11:41:40-04:00</created-at>
    <email>[email protected]</email>
    <first-name>Colin</first-name>
    <id type="integer">3</id>
    <last-name>Patterson</last-name>
    <logged-in-at type="datetime">2012-05-08T01:24:51-04:00</logged-in-at>
    <login>cpatterson746</login>
...

For JSON, send a HTTP GET such as:

https://DNS.record.for.rXg/admin/scaffolds/accounts/index/3.json

Results in the following output:

{"created_at":"2012-05-10T11:41:40-04:00",
 "email":"[email protected]","first_name":"Colin","id":3,
 "last_name":"Patterson","logged_in_at":"2012-05-08T01:24:51-04:00",
 "login":"cpatterson746",
...
}

It is also necessary to set the Content-Type HTTP header to the appropriate value (e.g., application/xml for XML) when using the optional format parameters.

Data Flow: External System Integration via RESTful API

The following diagrams illustrate how external systems integrate with the rXg through its RESTful API, including the proposed Subscriber and Content Policy System (SCPS) integration pattern using event-driven messaging.

RESTful API Integration Pattern

The rXg RESTful API enables external systems to perform CRUD operations on any scaffold. The following diagram shows how a typical external provisioning system interacts with the rXg.

sequenceDiagram
    participant EXT as External System<br/>(OSS/BSS, CRM, SCPS)
    participant API as rXg RESTful API<br/>(HTTPS + API Key)
    participant DB as rXg Database
    participant RXG as rXg Backend<br/>(rxgd)
    participant NET as Network<br/>(Data Plane)

    Note over EXT,NET: Provisioning a New Subscriber

    EXT->>API: POST /admin/scaffolds/accounts/create.json<br/>(api_key, record: {login, name, email, ...})
    API->>API: Authenticate API key<br/>(verify admin permissions)
    API->>DB: Create Account record
    DB-->>API: Account created (id: 42)
    API-->>EXT: 200 OK + JSON response<br/>(account attributes)

    EXT->>API: POST /admin/scaffolds/accounts/update/42.json<br/>(api_key, record: {usage_plan: 5, do_apply_usage_plan: 1})
    API->>DB: Update Account + apply Usage Plan
    DB->>DB: TriggerCallbacks fire<br/>(policy recalculation)
    DB-->>API: Account updated
    API-->>EXT: 200 OK

    Note over EXT,NET: Configuration Change Propagates to Network

    DB->>RXG: Trigger: account updated
    RXG->>RXG: Recalculate policy for account devices
    RXG->>NET: Update PF rules, bandwidth queues,<br/>NAT assignments

    Note over EXT,NET: Querying Subscriber State

    EXT->>API: GET /admin/scaffolds/login_sessions/index.json<br/>(api_key, search: "subscriber_mac")
    API->>DB: Query LoginSession records
    DB-->>API: Matching sessions
    API-->>EXT: 200 OK + JSON<br/>(session details, traffic stats, policy)

    EXT->>API: GET /admin/scaffolds/nat_assignments/index.json<br/>(api_key, search: "subscriber_ip")
    API->>DB: Query NatAssignment records
    DB-->>API: NAT mapping details
    API-->>EXT: 200 OK + JSON<br/>(source_ip, nat_ip, uplink, is_binat)

Proposed: Event-Driven Integration via Webhooks

For real-time event streaming to external systems (such as an SCPS, Kafka consumer, or analytics platform), the rXg uses its webhook and notification action system to push events as they occur.

sequenceDiagram
    participant SUB as Subscriber
    participant RXG as rXg Gateway
    participant DB as rXg Database
    participant NA as Notification Action<br/>(Watch Scaffold)
    participant WH as Webhook Engine
    participant EXT as External System<br/>(SCPS / Kafka / Analytics)

    Note over SUB,EXT: Event: Subscriber Login

    SUB->>RXG: Authenticate (portal / RADIUS)
    RXG->>DB: Create LoginSession
    DB->>NA: Watch Scaffold trigger<br/>(model: LoginSession, action: create)
    NA->>WH: Fire associated webhook

    WH->>WH: Render webhook body<br/>(ERB template with session data)
    WH->>EXT: POST /events/session-start<br/>(JSON: login, IP, MAC,<br/>policy, account, timestamp)
    EXT-->>WH: 200 OK

    Note over SUB,EXT: Event: Policy Change

    RXG->>DB: Update LoginSession<br/>(policy shift, VLAN change)
    DB->>NA: Watch Scaffold trigger<br/>(model: LoginSession, action: update)
    NA->>WH: Fire webhook
    WH->>EXT: POST /events/session-update<br/>(JSON: new policy, new VLAN,<br/>reason for change)

    Note over SUB,EXT: Event: Subscriber Logout

    SUB->>RXG: Disconnect / session expires
    RXG->>DB: Destroy LoginSession
    DB->>NA: Watch Scaffold trigger<br/>(model: LoginSession, action: delete)
    NA->>WH: Fire webhook
    WH->>WH: Use record_hash<br/>(record already deleted)
    WH->>EXT: POST /events/session-stop<br/>(JSON: final traffic stats,<br/>session duration, terminate cause)

    Note over SUB,EXT: Event: NAT Assignment Change

    DB->>NA: Watch Scaffold trigger<br/>(model: NatAssignment, action: create)
    NA->>WH: Fire webhook
    WH->>EXT: POST /events/nat-assignment<br/>(JSON: source_ip, nat_ip,<br/>uplink, is_binat, account)

Proposed: SCPS Subscriber Policy Control (Future Architecture)

Note: The following diagram represents a proposed architecture for Subscriber and Content Policy System (SCPS) integration. This event-driven pattern uses the rXg's existing webhook infrastructure and RESTful API as the integration layer between the rXg BNG (Broadband Network Gateway) and an external policy control system.

sequenceDiagram
    participant UE as Subscriber Device
    participant BNG as rXg BNG<br/>(Data Plane)
    participant CP as rXg Control Plane
    participant API as rXg RESTful API
    participant SCPS as SCPS<br/>(Policy Control)
    participant MSG as Message Bus<br/>(Webhook / Kafka)

    Note over UE,MSG: Subscriber Session Establishment

    UE->>BNG: Connect + DHCP + Auth
    BNG->>CP: LoginSession created
    CP->>MSG: Webhook: session-start<br/>(subscriber ID, IP, MAC, plan)
    MSG->>SCPS: Deliver session event

    SCPS->>SCPS: Evaluate subscriber policy<br/>(tier, quotas, content rules)
    SCPS->>API: PUT /accounts/update<br/>(apply bandwidth queue,<br/>content filter profile)
    API->>CP: Update policy configuration
    CP->>BNG: Push updated PF rules<br/>(TriggerCallback)
    BNG->>BNG: Apply policy to subscriber traffic

    Note over UE,MSG: Mid-Session Policy Change

    SCPS->>SCPS: Detect quota threshold<br/>(e.g., 80% data usage)
    SCPS->>API: PUT /accounts/update<br/>(shift to throttled tier)
    API->>CP: Policy update
    CP->>BNG: Reconfigure bandwidth queue
    BNG->>UE: Throttled speed applied

    Note over UE,MSG: Session Teardown

    UE->>BNG: Disconnect
    BNG->>CP: LoginSession destroyed
    CP->>MSG: Webhook: session-stop<br/>(final stats, duration)
    MSG->>SCPS: Deliver termination event
    SCPS->>SCPS: Finalize billing record