API v2 Now Generally Available!

[jaredhendrickson13]

API v2 Now Generally Available & Upgrade Guide

Exciting news! API v2 is now generally available. This release introduces a completely redesigned API, offering a more consistent, powerful, and flexible experience. Key features and improvements include:

• New Framework: The REST API has been entirely rewritten including a new framework, providing a consistent experience across all endpoints while enhancing security, speed, and extensibility.
• Strict Schema: The API now enforces strict schema validation for all requests and responses, ensuring data consistency.
• Multiple Authentication Methods: Support for multiple simultaneous authentication methods.
• HATEOAS Support: HATEOAS (Hypermedia as the Engine of Application State) is now available as an opt-in feature, allowing clients to easily navigate and interact with related resources via links provided in responses.
• New Endpoints: Highly requested endpoints for WireGuard and HAProxy, along with many others, are now available in v2.
• Improved Documentation: The new framework integrates with the OpenAPI specification, enabling automatic generation of up-to-date and accurate API documentation.
• Enhanced Security Options: Notable new security features include:
  • Advanced API access list capabilities, allowing administrators to set API access rules for specific users and apply schedules to control when the API is accessible.
  • Dedicated privileges for each API endpoint and their available HTTP methods, permitting administrators to fine-tune user permissions without granting broader webConfigurator access. For more details on permissions in v2, refer to the Authorization documentation.

For a comprehensive list of changes, see the v2 release changelog.

Upgrade Guide

Before Installing

Important considerations before upgrading:

1. Breaking Changes: Existing v1 integrations are incompatible with v2 due to the amount of changes and the new endpoint URLs. Code updates will be necessary to use v2 endpoints.
2. Separate Installations: v2 is packaged separately from v1, allowing both to be installed concurrently. You can continue using v1 while you migrate to v2.
3. Package name: The package name for v2 is pfSense-pkg-RESTAPI; for v1, it is pfSense-pkg-API. For more details, see the FAQs.
4. Upgrade Path: There is no direct upgrade path from v1 to v2. Install the v2 package alongside v1 and migrate your code to the new endpoints. Uninstall the v1 package once migration is complete.
5. UI Page Path: The UI page for v2 settings is located at System > REST API, whereas the v1 settings UI page is at System > API. UI pages and settings are specific to each version.
6. Command Line: The v2 command line tool is named pfsense-restapi, while the v1 tool is pfsense-api. These tools are version-specific and not interchangeable.
7. Feature Parity: Nearly all v1 features have been redesigned for v2, though some may be unavailable or operate differently.

Warning

• When v1 and v2 are installed concurrently, some dependencies are shared. Ensure both packages are kept up-to-date to ensure compatibility.
• Before v1.7.5, it was possible for v1 to see the v2 package as a valid update candidate in the UI and CLI. This issue has been resolved in v1.7.5 and later versions. If you are planning to run both v1 and v2 concurrently, It is recommended to upgrade to v1.7.5 before installing the v2 package to prevent issues when installing v2.

Caution

v2 does not install cleanly on 32-bit builds of pfSense Plus 24.03 (Netgate 3100) and will cause the pfSense webConfigurator to throw errors. It is recommended to use v1 for 32-bit systems instead. See #502 for more information.

Installation

To install v2, run the following command:

pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/releases/download/v2.0.0/pfSense-2.7.2-pkg-RESTAPI.pkg

Note

• Adjust the pfSense version number in the URL (e.g., 2.7.2) to match your pfSense version. Refer to the releases page for available builds.
• Unlike v1, restarting the web server post-installation is unnecessary, as v2 handles it automatically in the background.

Next Steps

• After installing v2, you can start using the new API. For usage information, refer to the new package guide.
• Access the built-in Swagger documentation within your pfSense instance or view the public Swagger documentation.

Future of v1

The v1 codebase has been moved to the legacy branch and will continue receiving bug fixes and security updates for the foreseeable future. No new features will be added. It's recommended to migrate to v2 to take advantage of the latest features and improvements.

Need Help?

If you have questions or need assistance with the upgrade and migration process, please open a discussion.

Thank you

Many thanks to all those who helped make this release happen! Whether it be opening issues, PRs, or just spreading the word about the project. The input and assistance from the community over the last few years has helped immensely in shaping this release. I am truly grateful for the support.

[tehniemer]

What's the method to uninstall the v1 API?

[jaredhendrickson13]

Using the command line, pkg-static delete pfSense-pkg-API will uninstall the v1 package.