pfSense REST API

https://pfrest.org/
Admin
An unofficial open-source REST and GraphQL API for pfSense CE and pfSense Plus firewalls with 200+...
Tokens:229,855
Snippets:1,608
Trust Score:5.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup Mkdocs Development Server

Source: https://pfrest.org/CONTRIBUTING

Install Python dependencies and start the Mkdocs local development server to preview documentation changes. Requires Python 3.

```bash
python3 -m pip install -r requirement.txt
mkdocs serve

```

--------------------------------

### GET /api/v2/examples (Query Filtering)

Source: https://pfrest.org/QUERIES_FILTERS_AND_SORTING

Describes how to apply various filters to GET requests on plural endpoints to refine the returned data.

```APIDOC
## GET /api/v2/examples

### Description
Filter data returned from plural endpoints using query parameters. Filters are appended to field names using double underscores (e.g., fieldname__filter=value).

### Method
GET

### Endpoint
/api/v2/examples

### Query Parameters
- **fieldname__exact** (string) - Optional - Matches field value exactly.
- **fieldname__startswith** (string) - Optional - Matches if field starts with value.
- **fieldname__endswith** (string) - Optional - Matches if field ends with value.
- **fieldname__contains** (string) - Optional - Matches if field contains value.
- **fieldname__in** (array/string) - Optional - Matches if field is in provided list or is a substring.
- **fieldname__lt** (integer) - Optional - Less than.
- **fieldname__lte** (integer) - Optional - Less than or equal to.
- **fieldname__gt** (integer) - Optional - Greater than.
- **fieldname__gte** (integer) - Optional - Greater than or equal to.
- **fieldname__format** (string) - Optional - Matches specific format (e.g., ipv4, email).
```

--------------------------------

### GET /api/v1/system/help

Source: https://pfrest.org/php-docs/namespaces/restapi-contenthandlers.html

Prints the pfsense-restapi help page.

```APIDOC
## GET /api/v1/system/help

### Description
Prints the pfsense-restapi help page.

### Method
GET

### Endpoint
/api/v1/system/help
```

--------------------------------

### Install pfSense REST API package

Source: https://pfrest.org/INSTALL_AND_CONFIG

Use these commands to install the package on pfSense CE or pfSense Plus via the command line.

```shell
pkg-static add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-2.8.1-pkg-RESTAPI.pkg
```

```shell
pkg-static -C /dev/null add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-25.11-pkg-RESTAPI.pkg
```

--------------------------------

### GET /help

Source: https://pfrest.org/php-docs/files/pfsense-pkg-restapi-files-usr-local-pkg-restapi-resources-scripts-manage.html

Prints the pfsense-restapi help page.

```APIDOC
## GET /help

### Description
Prints the pfsense-restapi help page.

### Method
GET

### Endpoint
/help
```

--------------------------------

### Get API Help

Source: https://pfrest.org/php-docs/namespaces/restapi-auth.html

Prints the pfSense-pkg-RESTAPI help page.

```APIDOC
## GET /api/help

### Description
Displays the help information for the pfSense-pkg-RESTAPI.

### Method
GET

### Endpoint
/api/help

### Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **help_text** (string) - The help documentation for the API.

#### Response Example
```json
{
  "help_text": "Usage: ...\nAvailable commands: ..."
}
```
```

--------------------------------

### Generate PHPDoc via Docker

Source: https://pfrest.org/CONTRIBUTING

This method uses Docker to build the PHPDoc documentation and start a local development server. Ensure Docker is installed and running.

```bash
# Build the docs using Docker
docker run --rm -v $(pwd):/data phpdoc/phpdoc run -c phpdoc.dist.xml

# Start a local development server
cd .phpdoc/build
php -S localhost:8000

```

--------------------------------

### Set GET Request Help Text

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Endpoint.html

Sets the GET request's OpenAPI documentation for this Endpoint. This will be used when generating the OpenAPI documentation for this Endpoint. This is typically only necessary if the default description is not adequate.

```php
public string $get_help_text = '';
```

--------------------------------

### GET /version

Source: https://pfrest.org/php-docs/files/pfsense-pkg-restapi-files-usr-local-pkg-restapi-resources-scripts-manage.html

Prints the pfSense-pkg-RESTAPI version information.

```APIDOC
## GET /version

### Description
Prints the pfSense-pkg-RESTAPI version information.

### Method
GET

### Endpoint
/version
```

--------------------------------

### GET /api/v1/system/version

Source: https://pfrest.org/php-docs/namespaces/restapi-contenthandlers.html

Prints the pfSense-pkg-RESTAPI version information.

```APIDOC
## GET /api/v1/system/version

### Description
Prints the pfSense-pkg-RESTAPI version information.

### Method
GET

### Endpoint
/api/v1/system/version
```

--------------------------------

### REST API Package Installation

Source: https://pfrest.org/php-docs/namespaces/restapi-queryfilters.html

This function runs automatically upon installation of the REST API package to reload the webConfigurator and apply necessary nginx changes, eliminating the need for manual webGUI restarts.

```APIDOC
## REST API Package Installation

### Description
Automatically reloads the webConfigurator and applies nginx changes required for the REST API package upon installation.

### Method
N/A (Automatic on install)

### Endpoint
N/A
```

--------------------------------

### System Packages API

Source: https://pfrest.org/php-docs/namespaces/restapi-endpoints.html

Endpoint for listing all installed software packages.

```APIDOC
## GET /websites/pfrest/api/system/packages

### Description
Retrieves a list of all installed software packages on the system.

### Method
GET

### Endpoint
/websites/pfrest/api/system/packages

### Response
#### Success Response (200)
- **packages** (array of objects) - A list of installed packages.
  - **name** (string) - The name of the package.
  - **version** (string) - The installed version.

#### Response Example
```json
{
  "packages": [
    {
      "name": "nginx",
      "version": "1.20.1"
    },
    {
      "name": "openssh",
      "version": "8.4p1"
    }
  ]
}
```
```

--------------------------------

### Generate PHPDoc via Phar

Source: https://pfrest.org/CONTRIBUTING

Use this method to download the PHPDoc Phar, build the documentation using the configuration file, and start a local development server.

```bash
# Download the phpdoc phar
wget https://phpdoc.org/phpDocumentor.phar
chmod +x phpDocumentor.phar

# Build the docs
./phpDocumentor.phar -c phpdoc.dist.xml

# Start a local development server
cd .phpdoc/build
php -S localhost:8000

```

--------------------------------

### Check pfSense Package Dependencies

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Verifies that all required pfSense packages are installed and that package include files can be found. Throws NotFoundError for missing packages and ServerError for missing include files.

```PHP
    /**
     * Checks if the required pfSense packages for this model are installed.
     * @throws NotFoundError When the Model requires a pfSense package that is not installed.
     * @throws ServerError When a package requires a PHP include file that could not be found.
     */
    private function check_packages() {
        # Loop through each required package and ensure it is present on the system.
        foreach ($this->packages as $pkg) {
            # Return an error if the package is not installed
            if (!is_pkg_installed($pkg)) {
                throw new NotFoundError(
                    message: "The requested action requires the '$pkg' package but it is not installed.",
                    response_id: 'MODEL_MISSING_REQUIRED_PACKAGE',
                );
            }
        }

        # Loop through each package dependency and add it.
        foreach ($this->package_includes as $include) {
            if (!include_once $include) {
                throw new ServerError(
                    message: "Model requires include file $include but it could not be found in the PHP path.",
                    response_id: 'MODEL_WITH_FAILED_INCLUDE',
                );
            }
        }
    }
```

--------------------------------

### restart_webgui

Source: https://pfrest.org/php-docs/namespaces/default.html

Restarts the webConfigurator in the background. This is automatically run on package installation.

```APIDOC
## restart_webgui

### Description
Restarts the webConfigurator in the background. This is automatically run on package installation.

### Method
Not specified (likely a script execution, not a direct API endpoint)

### Endpoint
Not specified

### Notes
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.
```

--------------------------------

### GET /manage/version

Source: https://pfrest.org/php-docs/namespaces/restapi-fields.html

Retrieves the version information for the pfSense-pkg-RESTAPI package.

```APIDOC
## GET /manage/version

### Description
Prints the pfSense-pkg-RESTAPI version information.

### Method
GET

### Endpoint
/manage/version
```

--------------------------------

### PHPUnit-like TestCase for pfSense

Source: https://pfrest.org/CONTRIBUTING

Extend this class to write tests within the pfSense environment. Methods starting with 'test' will be executed. Ensure tests clean up any configuration changes.

```php
<?php

namespace RESTAPI\Tests;

require_once('RESTAPI/autoloader.inc');

use RESTAPI\Core\TestCase;

class MyTestCase extends TestCase
{
    public function test_something()
    {
        # Add your test logic here
        $this->assert_is_true(true);
    }
}

```

--------------------------------

### Specify Required pfSense Packages

Source: https://pfrest.org/BUILDING_CUSTOM_MODEL_CLASSES

List the pfSense packages required for the Model to function. An error is thrown if these packages are not installed when attempting to create, update, or delete objects. Package names must include the `pfSense-pkg-` prefix.

```php
$this->packages = ['pfSense-pkg-nmap', 'pfSense-pkg-sudo'];
```

--------------------------------

### PHP Autoloader and Namespace Setup

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

This snippet demonstrates the autoloader inclusion and namespace declarations required for the RESTAPI Core library. It includes copyright information and license details.

```php
<?php
//   Copyright 2024 Jared Hendrickson
//
//   Licensed under the Apache License, Version 2.0 (the "License");
//   you may not use this file except in compliance with the License.
//   You may obtain a copy of the License at
//
//       http://www.apache.org/licenses/LICENSE-2.0
//
//   Unless required by applicable law or agreed to in writing, software
//   distributed under the License is distributed on an "AS IS" BASIS,
//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//   See the License for the specific language governing permissions and
//   limitations under the License.

namespace RESTAPI\Core;

require_once 'RESTAPI/autoloader.inc';

use RESTAPI;
use RESTAPI\Responses\ConflictError;
use RESTAPI\Responses\ForbiddenError;
use RESTAPI\Responses\NotFoundError;
use RESTAPI\Responses\ServerError;
use RESTAPI\Responses\ServiceUnavailableError;
use RESTAPI\Responses\ValidationError;
use function RESTAPI\Core\Tools\get_classes_from_namespace;

```

--------------------------------

### help()

Source: https://pfrest.org/php-docs/namespaces/default.html

Prints the help documentation for the pfsense-restapi.

```APIDOC
## help()

### Description
Prints the pfsense-restapi help page.
```

--------------------------------

### Configure GET Request Privileges

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Endpoint.html

Assigns pfSense privileges that should allow GET requests to this Endpoint. This property is dynamically populated.

```php
public array $get_privileges = [];
```

--------------------------------

### help Function

Source: https://pfrest.org/php-docs/namespaces/restapi-dispatchers.html

Prints the pfSense-RESTAPI help page.

```APIDOC
## help()

### Description
Prints the pfSense-RESTAPI help page.

### Method
N/A (This appears to be a function call within the PHP environment, not a direct HTTP endpoint).

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (void)
This function returns void, indicating it performs an action (printing help) rather than returning data.

### Response Example
N/A
```

--------------------------------

### Custom Query Filter Class Example

Source: https://pfrest.org/BUILDING_CUSTOM_QUERY_FILTER_CLASSES

This example demonstrates how to create a custom query filter by extending the \RESTAPI\Core\QueryFilter class. Implement the evaluate method to define the filter's logic. Ensure the class name matches the file name.

```php
<?php

namespace RESTAPI\QueryFilters;

require_once 'RESTAPI/autoloader.inc';

use RESTAPI\Core\QueryFilter;

class MyCustomQueryFilter extends QueryFilter {
    # Sets the name of the query filter that will be used in the query string
    public string $name = 'customfilter';

    # Sets the logic for the query filter. In this example, we are checking if the field value is equal to the filter value.
    public function evaluate(mixed $field_value, mixed $filter_value): bool {
        return $field_value == $filter_value;
    }
}

```

--------------------------------

### GET /api/v2/diagnostics/ping

Source: https://pfrest.org/php-docs/packages/RESTAPI.html

Endpoint for running ping diagnostics.

```APIDOC
## GET /api/v2/diagnostics/ping

### Description
Runs ping diagnostics.

### Method
GET

### Endpoint
/api/v2/diagnostics/ping
```

--------------------------------

### Implement the _process Method

Source: https://pfrest.org/BUILDING_CUSTOM_DISPATCHER_CLASSES

The _process method contains the logic to be executed in the background. Arguments must be passed via class properties as the method does not accept parameters.

```php
/**
 * Method to execute the Dispatcher operation
 */
protected function _process(): void {
    # TODO Add your operation code here
}
```

--------------------------------

### Display REST API Help

Source: https://pfrest.org/php-docs/namespaces/restapi-responses.html

Prints the help page for the pfSense REST API.

```php
help() : void
```

--------------------------------

### Build Form URL

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Form.html

Creates an endpoint file in the pfSense webroot to serve the form, returning true on success.

```php
    public function build_form_url(): bool {
        # Get the fully qualified and non qualified class names for this object
        $fq_class_name = get_class($this);
        $nq_class_name = $this->get_class_shortname();

        # Specify the PHP code to write to the Endpoints index.php file
        $code =
            "<?php\n" .
            "require_once('guiconfig.inc');\n" .
            "\$include = include('RESTAPI/Forms/$nq_class_name.inc');\n" .
            "if (!\$include) {\n" .
            "    http_response_code(503);\n" .
            "    echo '<h1>Service Unavailable</h1>';\n" .
            "    echo 'This resource is either not installed or is currently updating. Please try again later.';\n" .
            "    exit();\n" .
            "}\n" .
            "(new $fq_class_name())->print_form();\n";

        # Assign the absolute path to the file. Assume index.php filename if not specified.
        $filename = "/usr/local/www/$this->url";
        $filename = str_ends_with($filename, '.php') ? $filename : "$filename/index.php";
        mkdir(dirname($filename), 0644, true);
        file_put_contents($filename, $code);

        # Return true if the form was successfully built
        if (is_file($filename)) {
            return true;
        }
        return false;
    }
```

--------------------------------

### Initialize a Custom ContentHandler Class

Source: https://pfrest.org/BUILDING_CUSTOM_CONTENT_HANDLER_CLASSES

Use this template to create a new ContentHandler class. Place the file in /usr/local/pkg/RESTAPI/ContentHandlers/ with a .inc extension.

```php
<?php

namespace RESTAPI\ContentHandlers;

require_once 'RESTAPI/autoloader.inc';

use RESTAPI\Core\ContentHandler;

/**
 * TODO: Add a description of your ContentHandler class here.
 */
class MyCustomContentHandler extends ContentHandler {

}
```

--------------------------------

### Initialize Custom Cache Class

Source: https://pfrest.org/BUILDING_CUSTOM_CACHE_CLASSES

Use this template to create a new custom Cache class. Ensure the file is placed in the correct directory and named appropriately.

```php
<?php

namespace RESTAPI\Caches;

require_once 'RESTAPI/autoloader.inc';

use RESTAPI\Core\Cache;

/**
 * TODO: Add a description of your Cache class here.
 */
class MyCustomCache extends Cache {

}
```

--------------------------------

### GET /config/enabled

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Checks if a specific configuration value is enabled.

```APIDOC
## GET /config/enabled

### Description
Checks if a specific config value is set and enabled. Returns true if the key exists and has a non-null value.

### Method
GET

### Parameters
#### Query Parameters
- **path** (string) - Required - The configuration path.
- **enable_key** (string) - Optional - The key to check for enabled status (default: 'enable').
```

--------------------------------

### Create pfSense WebConfigurator Form Object

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Form.html

Populates and returns a pfSense webConfigurator \Form object. It iterates through defined sections, adds fields (handling sensitive fields as passwords), and appends global buttons with their configurations.

```PHP
final public function get_form(): \Form {
        # Create the Form object to assign sections and Fields to
        $form = new \Form();

        # Loop through each of the requested sections populate them
        foreach ($this->sections as $section_name => $section_params) {
            # Create the section object
            $section = new \Form_Section($section_name);

            # Add any custom classes defined
            $section->addClass(implode(' ', $section_params['classes'] ?? []));

            # Add any defined Fields to this section
            foreach ($section_params['fields'] as $section_field) {
                # Make this a password field if it is a sensitive field
                if ($this->model->$section_field->sensitive) {
                    $section->addPassword($this->model->$section_field->to_form_input());
                }
                # Otherwise, just add it as a normal input
                else {
                    $section->addInput($this->model->$section_field->to_form_input());
                }

                # Populate the default if present
            }

            # Add this section to the form
            $form->add($section);
        }

        # Add any defined buttons to the form globally
        foreach ($this->buttons as $button_name => $button_params) {
            $form
                ->addGlobal(
                    new \Form_Button(
                        name: $button_name,
                        title: $button_params['title'] ?: $button_name,
                        link: $button_params['link'],
                        icon: $button_params['icon'],
                    ),
                )
                ->addClass(implode(' ', $button_params['classes'] ?? []))
                ->setOnclick($button_params['on_click']);
        }

        return $form;
    }
```

--------------------------------

### Get API Version

Source: https://pfrest.org/php-docs/namespaces/restapi-queryfilters.html

Retrieves the version information for the pfSense-pkg-RESTAPI.

```APIDOC
## GET /api/version

### Description
Prints the pfSense-pkg-RESTAPI version information.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **version** (string) - The current version of the pfSense-pkg-RESTAPI.
```

--------------------------------

### Default Create Method

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Initializes the default '_create' method. For Models with a 'config_path' and 'many' set, this method automatically obtains the next model ID and writes the object to the pfSense config. Other Models require this method to be overridden.

```php
protected _create() : mixed
```

--------------------------------

### Web GUI Management

Source: https://pfrest.org/php-docs/namespaces/restapi-schemas.html

Restarts the pfSense webConfigurator.

```APIDOC
## POST /webgui/restart

### Description
Restarts the webConfigurator in the background.

### Method
POST

### Endpoint
/webgui/restart

### Parameters
(None)

### Request Body
(Not applicable)

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "WebGUI restarting"
}
```
```

--------------------------------

### GET /api/v2/firewall/rules

Source: https://pfrest.org/api-docs

Retrieves a list of all configured firewall rules.

```APIDOC
## GET /api/v2/firewall/rules

### Description
Retrieves the current list of firewall rules defined on the system.

### Method
GET

### Endpoint
/api/v2/firewall/rules
```

--------------------------------

### Read All Method

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Fetches Model objects for all objects stored in the internal pfSense values. If `config_path` is set, this will load Model objects for each object stored at the config path. If `internal_callable` is set, this will create Model objects for each object returned by the specified callable.

```APIDOC
## read_all()

### Description
Fetches Model objects for all objects stored in the internal pfSense values. If `config_path` is set, this will load Model objects for each object stored at the config path. If `internal_callable` is set, this will create Model objects for each object returned by the specified callable.

### Method
`public static read_all([int $limit = 0 ][, int $offset = 0 ][, bool $reverse = false ])`

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of Model objects to retrieve. This is only applicable to $many enabled Models.
- **offset** (int) - Optional - The starting point in the dataset to be used with $limit. This is only applicable to $many enabled Models.
- **reverse** (bool) - Optional - Set to true to reverse the order of the ModelSet. This is only applicable to $many enabled Models.

### Return values
ModelSet|Model — Returns a ModelSet of Models if `many` is enabled or a single Model object if `many` is not enabled.
```

--------------------------------

### GET /generate_pfsense_privs

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Form.html

Generates the pfSense privilege configuration array for the form.

```APIDOC
## GET /generate_pfsense_privs

### Description
Generates a pfSense privilege list entry array based on the Form's URL and verbose name, suitable for inclusion in the pfSense privilege system.

### Method
GET

### Endpoint
/generate_pfsense_privs

### Response
#### Success Response (200)
- **privileges** (array) - The pfSense priv list entry array corresponding to the privileges of this Endpoint.
```

--------------------------------

### version()

Source: https://pfrest.org/php-docs/namespaces/default.html

Prints the current version information of the pfSense-pkg-RESTAPI.

```APIDOC
## version()

### Description
Prints the pfSense-pkg-RESTAPI version information.
```

--------------------------------

### GET /models/classes

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Retrieves a list of all available model classes within the system.

```APIDOC
## GET /models/classes

### Description
Obtains an array of all registered model classes.

### Method
GET

### Parameters
#### Query Parameters
- **shortnames** (bool) - Optional - If true, returns only the short names of the model classes.
```

--------------------------------

### Get Model Cache Singleton

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Provides access to the ModelCache singleton instance.

```PHP
return ModelCache::get_instance();
```

--------------------------------

### Initialize Configuration at a Specific Path

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Initializes the configuration array for a given path using the `config_init_path` function after normalizing the path. This prepares a section of the configuration to be populated.

```php
config_init_path(self::normalize_config_path($path));
```

--------------------------------

### GET /get_related_link

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Obtains a HAL resource link to a specific Model object.

```APIDOC
## GET /get_related_link

### Description
Obtains a HAL resource link to a specific Model object.

### Parameters
#### Query Parameters
- **model** (Model) - Required - The Model object to obtain a link for.
- **rel** (string) - Required - The HAL resource link name to assign this ResourceLink object.
- **method** (string) - Optional - The HTTP method (default: 'GET').
- **use_namespace** (bool) - Optional - Set to true to prefix this $rel with this project's HAL prefix value (default: true).

### Response
#### Success Response (200)
- **ResourceLink** (object) - The ResourceLink object containing the links and attributes of the given $model.
```

--------------------------------

### GET /field/openapi-schema

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Field.html

Converts the Field object into an OpenAPI schema property configuration.

```APIDOC
## GET /field/openapi-schema

### Description
Converts this Field object to a PHP array representation of an OpenAPI schema property configuration for documentation generation.

### Method
GET

### Response
#### Success Response (200)
- **array** (object) - A PHP array containing the field as an OpenAPI schema property configuration.
```

--------------------------------

### Spawn a Background Process

Source: https://pfrest.org/BUILDING_CUSTOM_DISPATCHER_CLASSES

Initiate the dispatcher operation. Setting async to true runs the task in the background, while false executes it synchronously in the main process.

```php
$dispatcher = new MyCustomDispatcher(async: true);
$dispatcher->spawn_process();
```

--------------------------------

### GET /get_related_links

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Obtains REST API links to resources related to this Model object.

```APIDOC
## GET /get_related_links

### Description
Obtains REST API links to resources related to this Model object.

### Response
#### Success Response (200)
- **ResourceLinkSet** (object) - A ResourceLinkSet containing REST API links to related Model objects.
```

--------------------------------

### To Internal Method

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Converts this Model object into its internal pfSense configuration form.

```APIDOC
## to_internal()

### Description
Converts this Model object into it's internal pfSense configuration form.

### Method
`public to_internal()`

### Return values
array<string|int, mixed>|string — The internal value suitable for writing to the pfSense configuration.
```

--------------------------------

### GET /field/related-models

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Field.html

Retrieves all related Model objects associated with the current Field value.

```APIDOC
## GET /field/related-models

### Description
Retrieves all related Model objects based on this Field's value. This method is intended for fields where $many is set to true.

### Method
GET

### Response
#### Success Response (200)
- **ModelSet** (object) - A collection of all related objects associated with this Field's current values.
```

--------------------------------

### Content Retrieval and Logging

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-ContentHandler.html

Methods for getting unprocessed content and writing log entries.

```APIDOC
## GET /api/content

### Description
Obtains the content from the remote client in its unprocessed form.

### Method
GET

### Endpoint
/api/content

### Response
#### Success Response (200)
- **content** (mixed) - The unprocessed content from the remote client.

#### Error Response (500 Internal Server Error)
- **error** (string) - Server error if the method is called but not overridden by a child class.

## POST /api/log

### Description
Writes a log entry to the applicable log file.

### Method
POST

### Endpoint
/api/log

### Parameters
#### Request Body
- **level** (int) - Required - The log level to write. This should be one of the LOG_* constants defined by syslog.
- **message** (string) - Required - The message to write to the log file.
- **logfile** (string) - Optional - The log file to write to. Defaults to 'restapi'.

### Response
#### Success Response (200)
- **status** (string) - Indicates successful logging.
```

--------------------------------

### Model Lifecycle and Configuration Methods

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Methods for managing the lifecycle of Model objects and interacting with the underlying pfSense configuration.

```APIDOC
## Model Lifecycle Methods

### create()
- **Description**: Perform validation, create this object internally and restart any associated services.

### delete()
- **Description**: Perform validation, delete this object internally and restart any associated services.

### copy()
- **Description**: Creates an unlinked copy of this Model object.

### from_representation(array $data)
- **Description**: Loads the Model object using an array representation of the object.

## Configuration Access

### get_config(string $path)
- **Description**: Read the value of specific configuration section by path.

### del_config(string $key)
- **Description**: Delete a key from the configuration.

### merge_config(array $data)
- **Description**: Merges provided data into the configuration.
```

--------------------------------

### GET /paginate

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Paginates a given array by obtaining a smaller subset based on limit and offset.

```APIDOC
## GET /paginate

### Description
Paginates a given array by obtaining a smaller subset based on limit and offset.

### Parameters
#### Query Parameters
- **array** (array) - Required - The array to paginate.
- **limit** (int) - Required - The maximum number of items to return.
- **offset** (int) - Required - The starting point in the array.
- **preserve_keys** (bool) - Optional - Set to true to preserve array keys (default: false).

### Response
#### Success Response (200)
- **array** (array) - The paginated array subset.
```

--------------------------------

### GET /field/references

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Field.html

Searches for existing Model objects that reference the current Field's value.

```APIDOC
## GET /field/references

### Description
Uses the Field's $referenced_by property to search for existing Model objects that reference this Field's current value.

### Method
GET

### Response
#### Success Response (200)
- **ModelSet** (object) - A collection of Model objects that reference this field.
```

--------------------------------

### GET /field/related-model

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Field.html

Retrieves the single related Model object associated with the current Field value.

```APIDOC
## GET /field/related-model

### Description
Retrieves the related Model object based on this Field's value. This method is intended for fields where $many is set to false.

### Method
GET

### Response
#### Success Response (200)
- **Model** (object) - The single Model object related to this Field's current value or null if not found.
```

--------------------------------

### version

Source: https://pfrest.org/php-docs/namespaces/restapi-models.html

Prints the current version information of the pfSense-pkg-RESTAPI.

```APIDOC
## version

### Description
Prints the pfSense-pkg-RESTAPI version information.
```

--------------------------------

### POST /restart_webgui

Source: https://pfrest.org/php-docs/files/pfsense-pkg-restapi-files-usr-local-pkg-restapi-resources-scripts-manage.html

Restarts the webConfigurator in the background.

```APIDOC
## POST /restart_webgui

### Description
Restarts the webConfigurator in the background.

### Method
POST

### Endpoint
/restart_webgui
```

--------------------------------

### GET /model

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Endpoint.html

Retrieves objects from the assigned model. Supports pagination and filtering for collection endpoints.

```APIDOC
## GET /model

### Description
Retrieves data from the model. If the endpoint is configured as 'many', it returns a collection with pagination; otherwise, it returns a single object.

### Method
GET

### Endpoint
/model

### Query Parameters
- **limit** (integer) - Optional - Number of items to return
- **offset** (integer) - Optional - Number of items to skip
- **sort_by** (string) - Optional - Field to sort by
- **sort_order** (string) - Optional - Sort direction
- **reverse** (boolean) - Optional - Reverse the result set
```

--------------------------------

### GET generate_pfsense_privs

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Form.html

Generates pfSense privileges specific to the Form class based on its URL properties.

```APIDOC
## GET generate_pfsense_privs

### Description
Utilizes the $url properties of this Form to generate pfSense privileges specific to this Form class. The resulting array is supplied to the pfSense privilege system.

### Method
GET

### Response
#### Success Response (200)
- **privileges** (array) - The pfSense priv list entry array corresponding to the privileges of this Endpoint.
```

--------------------------------

### Model Lifecycle Methods

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Methods for handling post-action application logic and configuration initialization.

```APIDOC
## apply_delete()

### Description
Performs steps and processes required to apply changes after the delete() method runs. This can be overridden to add custom steps to apply after delete actions only.

### Method
protected

## apply_replace_all(ModelSet $initial_objects, ModelSet $new_objects)

### Description
Performs steps and processes required to apply changes after the replace_all() method runs.

### Parameters
- **$initial_objects** (ModelSet) - Required - A ModelSet containing each existing object for this Model as they were when the replace_all() method was initially called.
- **$new_objects** (ModelSet) - Required - A ModelSet containing each of the new objects for this Model.

## init_config(mixed $path)

### Description
Initialize the configuration array of a specific config path.

### Parameters
- **$path** (mixed) - Required - string config path with '/' as separators
```

--------------------------------

### run_tests()

Source: https://pfrest.org/php-docs/namespaces/restapi-modeltraits.html

Runs all or select TestCase classes in \RESTAPI\Tests. This is only intended for development and should not be used on live installs.

```APIDOC
## run_tests()

### Description
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.

### Parameters
#### Arguments
- **$contains** (mixed) - Optional - Filter to run specific test cases.
```

--------------------------------

### System Information and Utilities

Source: https://pfrest.org/php-docs/namespaces/restapi-fields.html

Functions for retrieving version information, help documentation, and managing the web interface.

```APIDOC
## restart_webgui()

### Description
Restarts the webConfigurator in the background.

## version()

### Description
Prints the pfSense-pkg-RESTAPI version information.

## help()

### Description
Prints the pfsense-restapi help page.
```

--------------------------------

### Define XML Namespace for Field

Source: https://pfrest.org/BUILDING_CUSTOM_MODEL_CLASSES

Example of XML structure where a field is nested under a parent element.

```xml
<parent>
    <child>value</child>
</parent>
```

--------------------------------

### Initialize Custom Model Class

Source: https://pfrest.org/BUILDING_CUSTOM_MODEL_CLASSES

Use this template to create a new Model class. Ensure the file is saved in /usr/local/pkg/RESTAPI/Models/ with a .inc extension.

```php
<?php

namespace RESTAPI\Models;

require_once 'RESTAPI/autoloader.inc';

use RESTAPI\Core\Model;

/**
 * TODO: Add a description of your Model class here.
 */
class MyCustomModel extends Model {
    public function __construct(mixed $id = null, mixed $parent_id = null, mixed $data = [], mixed ...$options) {
        # TODO: Define Model attributes here

        # TODO: Define Model fields here

        parent::__construct($id, $parent_id, $data, ...$options);
    }
}
```

--------------------------------

### Get Privilege Name

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Form.html

Generates a consistent pfSense privilege name based on the form's URL property.

```php
    public function get_priv_name(): string {
        # Obtain the PHP file name for this Form using it's webroot URL
        $name = basename($this->url);

        # Remove the .php extension and convert underscores to hyphens
        $name = str_replace('.php', '', $name);
        $name = str_replace('_', '-', $name);

        # Return the privilege name prefixed with the `page-` privilege type
        return "page-$name";
    }
```

--------------------------------

### Restart WebGUI

Source: https://pfrest.org/php-docs/namespaces/restapi-caches.html

Restarts the webConfigurator in the background. This is automatically called upon package installation to apply necessary changes.

```APIDOC
## POST /restart_webgui

### Description
Restarts the webConfigurator in the background. This is automatically called upon package installation to apply necessary changes.

### Method
POST

### Endpoint
/restart_webgui

### Notes
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.
```

--------------------------------

### restart_webgui

Source: https://pfrest.org/php-docs/namespaces/restapi-fields.html

Function to reload the webConfigurator and apply necessary nginx changes.

```APIDOC
## restart_webgui

### Description
Reloads the webConfigurator and applies nginx changes required for the package to operate. This is typically called automatically upon installation.

### Method
Internal Function

### Response
- **void** - No return value.
```

--------------------------------

### GET /api/v2/schema/openapi

Source: https://pfrest.org/SWAGGER_AND_OPENAPI

Retrieves the full OpenAPI schema for the pfSense REST API, which can be used to generate client libraries and documentation.

```APIDOC
## GET /api/v2/schema/openapi

### Description
Retrieves the full OpenAPI schema definition for the pfSense REST API.

### Method
GET

### Endpoint
/api/v2/schema/openapi
```

--------------------------------

### Run Tests

Source: https://pfrest.org/php-docs/namespaces/restapi-caches.html

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.

```APIDOC
## Run Tests

### Description
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.

### Method
N/A (This describes a function's action, not a direct API endpoint)

### Endpoint
N/A

### Parameters
None explicitly defined for this function call.

### Request Example
N/A

### Response
#### Success Response (void)
This function returns void.

#### Response Example
N/A
```

--------------------------------

### backup() - Backup REST API Configuration

Source: https://pfrest.org/php-docs/namespaces/restapi-queryfilters.html

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

```APIDOC
## backup()

### Description
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`.

### Method
N/A (Function call within the package)

### Endpoint
N/A

### Parameters
None

### Request Body
None

### Response
#### Success Response (void)
This function does not return a value.
```

--------------------------------

### POST /config/set

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Sets a specific configuration value at a given path.

```APIDOC
## POST /config/set

### Description
Sets a configuration value at the specified path. Clears the model cache upon execution.

### Method
POST

### Parameters
#### Request Body
- **path** (string) - Required - The configuration path.
- **value** (mixed) - Required - The value to set.
- **default** (mixed) - Optional - The default value if the path does not exist.
```

--------------------------------

### Sorting API Data

Source: https://pfrest.org/QUERIES_FILTERS_AND_SORTING

Details the parameters used to sort data returned by GET requests or reorder objects within the pfSense configuration.

```APIDOC
## Sorting

### Description
Control the order of data returned or stored in the configuration using sorting parameters.

### Query Parameters
- **sort_by** (string) - Optional - The field to sort by.
- **sort_flags** (string) - Optional - Flags to modify sorting behavior.
- **sort_order** (string) - Optional - The order of sorting (e.g., ascending/descending).

### Usage Notes
- Sorting is only available for model objects that allow multiple instances.
- GET requests sort the returned data; POST/PATCH requests can reorder objects in the configuration.
```

--------------------------------

### Get Default Client Auth Object

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Obtains a default Auth object for the Model to use, setting the username to DEFAULT_CLIENT_USERNAME and IP address to DEFAULT_CLIENT_IP_ADDRESS.

```PHP
$client = new Auth();
$client->username = DEFAULT_CLIENT_USERNAME;
$client->ip_address = DEFAULT_CLIENT_IP_ADDRESS;
return $client;
```

--------------------------------

### Apply Create Changes

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Performs steps and processes required to apply changes after the `create()` method runs. This can be overridden to add custom steps applying for just create actions. Defaults to simply calling `apply()`.

```php
protected apply_create() : mixed
```

--------------------------------

### Get HTTP Status Message

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Response.html

Fetches the descriptive message for a given HTTP status code. Returns 'unknown' if the code is not found in the predefined list.

```php
final public static function get_http_status_message(int $http_status): string {
        # Return the message associated with this HTTP status code if it exists
        if (array_key_exists($http_status, HTTP_STATUS_MESSAGES)) {
            return HTTP_STATUS_MESSAGES[$http_status];
        }
        # Otherwise, return the message 'unknown'
        else {
            return 'unknown';
        }
    }
```

--------------------------------

### Model Constructor Options Handling

Source: https://pfrest.org/php-docs/classes/RESTAPI-Core-Model.html

Processes options passed to the Model constructor, setting properties like 'async', 'placement', and 'client'. Unrecognized options are returned for merging into the model's data.

```php
private function set_construct_options(array $options): array {
        # Set the async flag if given. Ensure this defaults to true.
        $this->async = $options['async'] ?? true;
        unset($options['async']);

        # Set the placement index if given and is a positive integer
        if (is_integer($options['placement']) and $options['placement'] >= 0) {
            $this->placement = $options['placement'];
            unset($options['placement']);
        }

        # Obtain a default $client Auth object for this Model object to use if one was not provided
        $this->client = $options['client'] ?: $this->get_default_client();
        unset($options['client']);

        return $options;
    }
```

--------------------------------

### Build webConfigurator forms

Source: https://pfrest.org/php-docs/namespaces/restapi-dispatchers.html

Generates PHP webConfigurator pages in the pfSense webroot based on defined Form classes.

```php
build_forms() : void
```

--------------------------------

### Run Tests

Source: https://pfrest.org/php-docs/namespaces/restapi-forms.html

Executes all or selected TestCase classes within the \RESTAPI\Tests namespace. This function is intended for development and testing purposes only and should not be used on live installations.

```APIDOC
## run_tests

### Description
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.

### Method
(Not specified, likely a script execution)

### Endpoint
(Not specified)

### Parameters
#### Query Parameters
- **contains** (mixed) - Optional - Only run tests that contain this sub-string in the test name.

### Request Example
(Not applicable)

### Response
#### Success Response (200)
- **void** - No explicit return value.

#### Response Example
(Not applicable)

### Notes
Tests will attempt to create, modify and delete configurations and files as well as restart services; which can be disruptive to live systems.
```
Tokens:
Raw