Important Changes Upcoming in REST API v2.7.0

[jaredhendrickson13]

Hi everyone,

I’m excited to share what’s coming in v2.7.0 in the coming weeks. This release will focus primarily on performance optimization, especially for larger pfSense environments. Not disrupting current integrations was a top priority; however, some changes needed to accomplish these performance improvements have forced certain previous behaviors to change slightly, as noted below. I strongly recommend all users read through these to understand how they may impact existing integrations.

What’s Coming

Performance Improvements

To address scalability issues on pfSense instances with large configurations, object caching and relation indexing are being implemented to greatly improve performance. While this change will primarily be noticed on instances with large configurations, the benefits will be applicable to all instances. This is being implemented in two ways:

• Caching: Objects will now be cached after the first read/query and automatically cleared once a configuration change is made via the API. This prevents redundant reloads of the same data.
• Indexing: Object relations are now indexed, meaning the API no longer has to iterate through every object to find a related field every time it is needed.

In both cases, the cache/index will only persist for that request. Subsequent requests cannot use a previous request's cache/index. While this shouldn't change how you use the API, it is a significant internal change. Please report any "stale" data issues you may encounter.

Expanded Query Capabilities (Parent/Child Models)

Previously, if an object had a parent assigned, you couldn't easily query child objects (e.g., DHCP server static mappings, DNS Resolver host override aliases, etc.) across all parents at once. Starting in v2.7.0, plural endpoints for these models are fully queryable across all parent objects. This applies to both read queries and deletion queries, making it much easier to manage nested resources without needing to know the specific parent ID beforehand.

This change should not break existing integrations; however, it may expand the scope of objects seen or considered by the API internally during related-object handling.

DHCP Server Refactor (Breaking Change!)

The /api/v2/services/dhcp_server endpoint has been updated to be more "REST-like" and better match the behavior of other endpoints. Previously, the API would automatically initialize DHCP servers for eligible interfaces, so it was never required to "create" a DHCP server. This caused issues with unexpected behavior, as DHCP servers could be initialized unexpectedly.

Starting with v2.7.0, it will be required to explicitly create new DHCP server objects via POST request. Once the DHCP server has been created, it can be updated via PATCH request as usual. This change also makes it possible to delete an existing DHCP server object via DELETE request.

If your integrations relied on the automatic initialization of new DHCP servers via PATCH requests, you will need to update your integrations to ensure those DHCP servers are created via POST request instead.

Repository Migration

Shortly after v2.7.0 drops, this repo will officially move from jaredhendrickson13/pfsense-api to pfrest/pfSense-pkg-RESTAPI. GitHub will automatically redirect requests from the old URL to the new URL following the migration.

If you are still on v1.8.0 or prior, please upgrade soon, as those legacy versions will likely have certain components break once the move is finalized. If you are running v1.8.1 or any v2.x version, you shouldn't need to take any action.

---

Development builds for v2.7.0 are available now for those able and willing to test. While automated testing suggests the build is stable, this release touches some lower-level logic, so I’d love to get some extra testing from the community. I am aiming for a full release in early January.

Thanks!