pfSense-pkg-RESTAPI

Documentation

Table of Contents

Packages

RESTAPI

Namespaces

RESTAPI

Constants

RESTAPI_LIBRARIES  = ['/usr/local/pkg/RESTAPI/Core/', '/usr/local/pkg/RESTAPI/Dispatchers/', '/usr/local/pkg/RESTAPI/Caches/', '/usr/local/pkg/RESTAPI/Responses/', '/usr/local/pkg/RESTAPI/Validators/', '/usr/local/pkg/RESTAPI/Fields/', '/usr/local/pkg/RESTAPI/ModelTraits/', '/usr/local/pkg/RESTAPI/Models/', '/usr/local/pkg/RESTAPI/QueryFilters/', '/usr/local/pkg/RESTAPI/ContentHandlers/', '/usr/local/pkg/RESTAPI/Schemas/', '/usr/local/pkg/RESTAPI/GraphQL/', '/usr/local/pkg/RESTAPI/Auth', '/usr/local/pkg/RESTAPI/Endpoints/', '/usr/local/pkg/RESTAPI/Forms/', '/usr/local/pkg/RESTAPI/Tests/']

Functions

build_endpoints()  : void
Builds a PHP API endpoint in the pfSense webroot for each Endpoint class defined in \RESTAPI\Endpoints using the Endpoint class's specified $url property.
build_forms()  : void
Builds a PHP webConfigurator page in the pfSense webroot for each Form class defined in \RESTAPI\Forms using the Form class's specified $url property.
remove_forms()  : void
Removes Forms (UI pages) built by the REST API package.
build_privs()  : void
Automatically creates pfSense privileges for each Endpoint class defined in \RESTAPI\Endpoints and each Form class defined in \RESTAPI\Forms.
build_schemas()  : void
Automatically generates the package schemas/documentation files for each Schema class defined in \RESTAPI\Schemas and writes them to /usr/local/pkg/RESTAPI/.resources/schemas/.
notify_dispatcher()  : void
Runs the process for a specified Dispatcher class in \RESTAPI\Dispatchers.
schedule_dispatchers()  : void
Creates cron jobs for all Dispatcher classes in \RESTAPI\Dispatchers and all Cache classes in \RESTAPI\Caches that have configured schedules.
unschedule_dispatchers()  : void
Removes the cron jobs for all Dispatcher classes in \RESTAPI\Dispatchers and all Cache classes in \RESTAPI\Caches with configured schedules.
refresh_cache()  : void
Refreshes the cache file by obtaining new day for a given Cache object.
run_tests()  : void
Runs all (or select) TestCase classes in \RESTAPI\Tests. This is only intended to test development of this package and should not be used on live installs.
restart_webgui()  : void
Restarts the webConfigurator in the background.
backup()  : void
Creates a backup of the REST API configuration if `keep_backup` is enabled. The backup will be stored in /usr/local/share/pfSense-pkg-RESTAPI/backup.json
restore()  : void
Restores the latest REST API configuration backup from /usr/local/share/pfSense-pkg-RESTAPI/backup.json
sync()  : void
Syncs the REST API configuration to HA peers if enabled.
update()  : void
Updates this package to the latest version available to this system
revert()  : void
Reverts or updates the REST API package to a specific version.
delete()  : void
Delete the REST API package and restart the webConfigurator to remove nginx changes.
rotate_server_key()  : void
Rotates the JWT server key. Warning: This will revoke any active JWTs.
version()  : void
Prints the pfSense-pkg-RESTAPI version information.
help()  : void
Prints the pfsense-restapi help page.
restapi_plugin_nginx()  : string
The pfSense-pkg-RESTAPI's 'plugin_nginx' package hook. This function is automatically called by the pfSense package system to add custom NGINX configurations. For this packacge, this function ensures an nginx server block is defined for API endpoints to allow the utiliziation of additional HTTP methods like PUT, PATCH and DELETE and URLs without a trailing slash.

Constants

RESTAPI_LIBRARIES

public mixed RESTAPI_LIBRARIES = ['/usr/local/pkg/RESTAPI/Core/', '/usr/local/pkg/RESTAPI/Dispatchers/', '/usr/local/pkg/RESTAPI/Caches/', '/usr/local/pkg/RESTAPI/Responses/', '/usr/local/pkg/RESTAPI/Validators/', '/usr/local/pkg/RESTAPI/Fields/', '/usr/local/pkg/RESTAPI/ModelTraits/', '/usr/local/pkg/RESTAPI/Models/', '/usr/local/pkg/RESTAPI/QueryFilters/', '/usr/local/pkg/RESTAPI/ContentHandlers/', '/usr/local/pkg/RESTAPI/Schemas/', '/usr/local/pkg/RESTAPI/GraphQL/', '/usr/local/pkg/RESTAPI/Auth', '/usr/local/pkg/RESTAPI/Endpoints/', '/usr/local/pkg/RESTAPI/Forms/', '/usr/local/pkg/RESTAPI/Tests/']

Functions

build_endpoints()

Builds a PHP API endpoint in the pfSense webroot for each Endpoint class defined in \RESTAPI\Endpoints using the Endpoint class's specified $url property.

build_endpoints() : void

build_forms()

Builds a PHP webConfigurator page in the pfSense webroot for each Form class defined in \RESTAPI\Forms using the Form class's specified $url property.

build_forms() : void

remove_forms()

Removes Forms (UI pages) built by the REST API package.

remove_forms() : void

build_privs()

Automatically creates pfSense privileges for each Endpoint class defined in \RESTAPI\Endpoints and each Form class defined in \RESTAPI\Forms.

build_privs() : void

build_schemas()

Automatically generates the package schemas/documentation files for each Schema class defined in \RESTAPI\Schemas and writes them to /usr/local/pkg/RESTAPI/.resources/schemas/.

build_schemas() : void

notify_dispatcher()

Runs the process for a specified Dispatcher class in \RESTAPI\Dispatchers.

notify_dispatcher(string|null $dispatcher_name[, array<string|int, mixed> $arguments = [] ]) : void
Parameters
$dispatcher_name : string|null
$arguments : array<string|int, mixed> = []
Tags
note

This function does not call the Dispatcher process asynchronously, it will wait for the process to complete.

schedule_dispatchers()

Creates cron jobs for all Dispatcher classes in \RESTAPI\Dispatchers and all Cache classes in \RESTAPI\Caches that have configured schedules.

schedule_dispatchers() : void

unschedule_dispatchers()

Removes the cron jobs for all Dispatcher classes in \RESTAPI\Dispatchers and all Cache classes in \RESTAPI\Caches with configured schedules.

unschedule_dispatchers() : void

refresh_cache()

Refreshes the cache file by obtaining new day for a given Cache object.

refresh_cache(string|null $cache_name) : void
Parameters
$cache_name : string|null

The shortname of the Cache class that should have its cache file refreshed.

run_tests()

Runs all (or select) TestCase classes in \RESTAPI\Tests. This is only intended to test development of this package and should not be used on live installs.

run_tests([mixed $contains = '' ]) : void
Parameters
$contains : mixed = ''

string|null Only run tests that contain this sub-string in the test name.

Tags
note

Tests will attempt to create, modify and delete configurations and files as well as restart services; which can be disruptive to live systems.

restart_webgui()

Restarts the webConfigurator in the background.

restart_webgui() : void
Tags
note

When this package is first installed, this function runs to automatically reload the webConfigurator and apply the nginx changes required for this package to operate. Thus eliminating the requirement for the user to run /etc/rc.restart_webgui after installation.

backup()

Creates a backup of the REST API configuration if `keep_backup` is enabled. The backup will be stored in /usr/local/share/pfSense-pkg-RESTAPI/backup.json

backup() : void

restore()

Restores the latest REST API configuration backup from /usr/local/share/pfSense-pkg-RESTAPI/backup.json

restore() : void

sync()

Syncs the REST API configuration to HA peers if enabled.

sync() : void

update()

Updates this package to the latest version available to this system

update() : void

revert()

Reverts or updates the REST API package to a specific version.

revert(mixed $tag) : void
Parameters
$tag : mixed

string semantic version tag to revert or upgrade to.

delete()

Delete the REST API package and restart the webConfigurator to remove nginx changes.

delete() : void

rotate_server_key()

Rotates the JWT server key. Warning: This will revoke any active JWTs.

rotate_server_key() : void

version()

Prints the pfSense-pkg-RESTAPI version information.

version() : void

help()

Prints the pfsense-restapi help page.

help() : void

restapi_plugin_nginx()

The pfSense-pkg-RESTAPI's 'plugin_nginx' package hook. This function is automatically called by the pfSense package system to add custom NGINX configurations. For this packacge, this function ensures an nginx server block is defined for API endpoints to allow the utiliziation of additional HTTP methods like PUT, PATCH and DELETE and URLs without a trailing slash.

restapi_plugin_nginx(mixed $pluginparams) : string
Parameters
$pluginparams : mixed

Plugin parameters passed in by the pfSense package system.

Return values
string —

The custom nginx block to be added to the webConfigurator's nginx.conf file

Search results