API v2 Development Builds Now Available!

[jaredhendrickson13]

I'm thrilled to announce the availability of development builds for API v2 on the release page! This update brings significant changes to both the underlying framework and API responses. v2 is a comprehensive redesign that addresses early development missteps and aligns components with RESTful principles. Here are some of the key enhancements:

Strict Schema

In v1, dynamic changes in field types caused challenges for developers. With v2, a new representation framework ensures consistent acceptance and representation of data in the correct data type at all times.

Embedded IDs

Object IDs are now conveniently included in the object's data in v2, alleviating the challenges faced in obtaining them in v1. This improvement makes IDs more apparent and easier to work with, despite being dynamic and subject to change due to sorting or deletions.

HATEOAS Enabled

Designed with HATEOAS at its core, v2 incorporates applicable links to resources in API responses. These links facilitate actions like object deletion, updating, and obtaining related objects.

API-Specific Privileges

Unlike v1, which shared privileges with webConfigurator pages, v2 introduces individual API privileges for each endpoint and its supported HTTP methods. This granular control enhances authorization over API calls, allowing administrators to specify privileges for each endpoint independently.

New Package Name

Starting with v2, the package will be named pfSense-pkg-RESTAPI, with the webConfigurator referring to it as REST API. This name change provides clarity and enables the coexistence of v1 and v2 as separate packages, allowing for continued development of v1 alongside v2.

New Framework

In v2, the framework has been entirely rebuilt, drawing inspiration from the Django web framework. This overhaul brings significant benefits, including a substantial reduction in code, accelerated API development, and vastly improved consistency. The framework, which can also be used as a PHP library for private packages on pfSense, offers several key features:

• Reusable Validation: Simplify validation by using reusable Validator objects assigned to Fields. This feature streamlines the enforcement of specific validations on Fields with minimal effort.

• Automatic Object Relations: Enjoy automatic retrieval of Model objects related to another Model object, eliminating the need for constant manual lookups. This feature can also be used to automatically prevent the deletion of objects in use by another Model object.

• Automatic OpenAPI Documentation: With explicit field definitions, the framework automatically generates accurate OpenAPI documentation using endpoint, model, and field attributes.

• Asynchronous Functions: Introducing Dispatchers, which are classes used to define background functions. Useful for time-consuming configurations, Dispatchers initiate processes without delaying API calls. Control the number and duration of these asynchronous processes seamlessly.

• Automatic webConfigurator Page Generator: Forms are classes within the framework which facilitate the automatic generation of a webConfigurator UI page by simply providing an existing Model object. These dynamic forms are customizable and update automatically with changes to your Models upon the next page refresh.

Note

Detailed framework documentation will be available in the coming months. In the meantime, feel free to check out the source files!

---

Important Considerations:

With these v2 pre-release builds, those who are able are encouraged to test and provide valuable feedback. However, please note the following:

1. Not Production Ready: v2 is not yet production-ready, and I am actively working to fix bugs and optimize performance.
2. Feature Parity: While the underlying framework and critical API endpoints are nearly complete, some features are still being ported over to v2. Expect ongoing additions and changes in the coming months.
3. Compatibility Warning: None of your existing v1 integrations will work with v2 due to changes in endpoint URLs, response schemas, and privileges.

Important

Feel free to open issues for identified problems, but hold off on issues regarding missing functionality until we approach a production-ready release.

Thank you for your support and collaboration!