pfSense-pkg-RESTAPI

Endpoint
in package

RESTAPI

uses BaseTraits

Defines an API Endpoint, encapsulating attributes essential for generating the PHP endpoint in the pfSense webroot, and facilitating API calls. Endpoints are also responsible for defining authentication requirements, request methods available, and allows customizing the generated OpenAPI documentation for the endpoint.

Properties

$append : bool
$async : bool
$auth_methods : array<string|int, mixed>
$decode_content_handlers : array<string|int, mixed>
$delete_help_text : string
$delete_privileges : array<string|int, mixed>
$deprecated : bool
$encode_content_handlers : array<string|int, mixed>
$get_help_text : string
$get_privileges : array<string|int, mixed>
$ignore_acl : bool
$ignore_enabled : bool
$ignore_interfaces : bool
$ignore_read_only : bool
$limit : int
$many : bool
$model : Model
$model_name : string
$offset : int
$patch_help_text : string
$patch_privileges : array<string|int, mixed>
$post_help_text : string
$post_privileges : array<string|int, mixed>
$put_help_text : string
$put_privileges : array<string|int, mixed>
$remove : bool
$request_data : array<string|int, mixed>
$request_method : string
$request_method_options : array<string|int, mixed>
$requires_auth : bool
$resource_link_set : ResourceLinkSet|null
$response_types : array<string|int, mixed>
$restapi_settings : RESTAPISettings
$reverse : bool
$sort_by : string|null
$sort_order : string
$tag : string
$url : string
$client : Auth
$errors : array<string|int, mixed>

Methods

__construct() : mixed: Sets values whenever the Endpoint object is crated.
build_endpoint_url() : bool: Generate an endpoint for this view in the pfSense webroot.
check_construct() : void: Checks for conflicting attributes during object construction.
check_decode_content_handler_supported() : void: Checks if the requested decode ContentHandler is supported.
check_encode_content_handler_supported() : void: Checks if the requested encode ContentHandler is supported.
generate_pfsense_privs() : array<string|int, mixed>: Utilizes the $url and $request_method_options properties of this Endpoint to generate pfSense privileges specific to this Endpoint class. The resulting array is then supplied to the pfSense privilege system located at /etc/inc/priv/.
get_class_fqn() : string: Obtains the fully qualified name of the called class.
get_class_shortname() : string: Obtains the shortname of the called class.
get_classes_in_namespace() : array<string|int, mixed>: Obtains all classes associated with this class's current namespace.
get_endpoint_filepath() : string: Obtains the absolute filepath to the PHP file generated for this Endpoint.
get_pagination_resource_links() : void: Obtains the `prev` and `next` HATEOAS resource links for pagination use. These links supply the previous and next set of objects from the dataset.
log_error() : void: Logs an error to the syslog.
process_request() : string: Processes the API request and returns the serialized API response to send back to the client.
response_handler() : Response: Defines a middleware method that can be used to handle the call's Response object before it is sent back to the client. This can be used by child Endpoints to extend or override the default Response handling behavior.
delete() : Model|ModelSet: Deletes an existing object for the assigned Model using the data submitted in a DELETE request.
get() : Model|ModelSet: Obtains the object data for GET requests to this Endpoint.
options() : void: Populates associated headers whenever an OPTIONS request is received.
patch() : Model|ModelSet: Updates an existing object for the assigned Model using the data submitted in a PATCH request.
post() : Model|ModelSet: Creates a new object for the assigned Model using the data submitted in a POST request.
put() : Model|ModelSet: Replaces all existing objects for the assigned Model using the data submitted in a PUT request.
check_acl() : void: Checks if the client is allowed to access this Endpoint according to the REST API Access List.
check_auth() : void: Checks if authentication and authorization for this Endpoint is successful. This will attempt authentication and authorization for each allowed auth method. Only one auth method needs to succeed to allow access.
check_enabled() : void: Checks if the API is enabled before allowing the call.
check_interface_allowed() : void: Checks if the interface receiving the API call is allowed to answer API calls.
check_request_data() : void: Checks if the API client's request data was successfully received and parsed by the API. This method populates the $this->request_data property according to the client's requested content-type.
check_request_method() : void: Check if the HTTP method requested by the API client is supported by this view.
get_default_privs() : void: Assigns the default privileges required to make API calls to this endpoint. This method will automatically populate the following properties:
get_method_priv_name() : string: Generates the privilege name necessary to execute a specific request method on this Endpoint.
get_required_privs() : array<string|int, mixed>: Retrieves the necessary privileges for processing the received API call.
set_default_help_text() : void: Determines the appropriate default help text for each method according to the assigned Model and Endpoint properties.
set_default_tag() : void: Use the endpoint's URL to determine a default OpenAPI tag for this endpoint.
validate_append() : void: Validates the $append common control parameter for this request.
validate_async() : void: Validates the $async common control parameter for this request.
validate_endpoint_fields() : void: Performs validation on non-Model fields. These fields control how Models are initially obtained/constructed.
validate_limit() : void: Validates the $limit common control parameter for this request.
validate_offset() : void: Validates the $offset common control parameter for this request.
validate_remove() : void: Validates the $remove common control parameter for this request.
validate_reverse() : void: Validates the $reverse common control parameter for this request.
validate_sort_by() : void: Validates the $sort_by common control parameter for this request.
validate_sort_order() : void: Validates the $sort_order common control parameter for this request.

$append


    public
        bool
    $append
     = false

Sets the default value for the append field in the request data. This value is used to control how Model objects apply updates to array fields on existing objects. If set to true, any requested updates to array fields will be appended to the existing array instead of replacing it. This value can be overridden by the client in the request data.

$async


    public
        bool
    $async
     = true

Sets the default value for the async field in the request data. This value is used to determine if the API call should be processed asynchronously when available. This value can be overridden by the client in the request data.

$auth_methods


    public
        array<string|int, mixed>
    $auth_methods
     = []

Explicitly specify authentication methods this Endpoint uses. Leave blank to use the authentication methods allowed by the REST API settings. If any authentication methods are specified here, this Endpoint will always allow authentication using this method, even if the method is not enabled in the REST API settings.

$decode_content_handlers


    public
        array<string|int, mixed>
    $decode_content_handlers
     = []

Defines which ContentHandler class (as shortnames) can be used to decode the API request. If this array is empty, all ContentHandlers with decode capabilities can be used. This directly relates to which MIME-types this endpoint supports in the Content-Type header.

$delete_help_text


    public
        string
    $delete_help_text
     = ''

Sets the DELETE 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.

$delete_privileges


    public
        array<string|int, mixed>
    $delete_privileges
     = []

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

$deprecated


    public
        bool
    $deprecated
     = false

Marks this Endpoint as deprecated in the OpenAPI documentation.

$encode_content_handlers


    public
        array<string|int, mixed>
    $encode_content_handlers
     = []

Defines which ContentHandler class (as shortnames) can be used to encode the API response. If this array is empty, all ContentHandlers with encode capabilities can be used. This directly relates to which MIME-types this endpoint supports in the Accept header.

$get_help_text


    public
        string
    $get_help_text
     = ''

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.

$get_privileges


    public
        array<string|int, mixed>
    $get_privileges
     = []

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

$ignore_acl


    public
        bool
    $ignore_acl
     = false

Allow this Endpoint to ignore the REST API Access List. By default, Endpoints will not accept API calls from clients that are not allowed by the REST API Access List. Setting this value to true will allow this Endpoint to respond to API calls from any client regardless of the REST API Access List.

$ignore_enabled


    public
        bool
    $ignore_enabled
     = false

Allow this Endpoint to ignore the enabled API setting. By default, Endpoints will not accept API calls when the API's enabled setting is disabled. Setting this value to true will allow this Endpoint to respond to API calls even if the API is disabled.

$ignore_interfaces


    public
        bool
    $ignore_interfaces
     = false

Allow this Endpoint to ignore the allowed_interfaces API setting. By default, if an Endpoint receives an API call on an interface not specified in the allowed_interfaces API setting, a ForbiddenError will be thrown. Setting this value to true will allow this Endpoint to respond to requests over any interface regardless of what is specified in allowed_interfaces.

$ignore_read_only


    public
        bool
    $ignore_read_only
     = false

Allow this Endpoint to ignore the current read_only API setting. By default, when the read_only API setting is enabled, Endpoints are only allowed to respond to GET requests. Setting this value to true will allow requests using any HTTP method even if read_only is enabled.

$limit


    public
        int
    $limit
     = 0

Sets the default limit for the number of Model objects to retrieve in a single call to this Endpoint. This value is used for pagination purposes and can be overridden by the client in the request data.

$many


    public
        bool
    $many
     = false

Indicates whether this Endpoint interacts with a single Model object (false) or many Model objects (true).

$model


    public
        Model
    $model

The actual Model object created for the assigned $model_name.

$model_name


    public
        string
    $model_name
     = ''

The name of the Model class this Endpoint interacts with (excluding the Model class's namespace).

$offset


    public
        int
    $offset
     = 0

Sets the default offset for the starting point in the dataset requested for pagination. This value is used for pagination purposes and can be overridden by the client in the request data.

$patch_help_text


    public
        string
    $patch_help_text
     = ''

Sets the PATCH 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.

$patch_privileges


    public
        array<string|int, mixed>
    $patch_privileges
     = []

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

$post_help_text


    public
        string
    $post_help_text
     = ''

Sets the POST 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.

$post_privileges


    public
        array<string|int, mixed>
    $post_privileges
     = []

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

$put_help_text


    public
        string
    $put_help_text
     = ''

Sets the PUT 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.

$put_privileges


    public
        array<string|int, mixed>
    $put_privileges
     = []

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

$remove


    public
        bool
    $remove
     = false

Sets the default value for the remove field in the request data. This value is used to control how Model objects apply updates to array fields on existing objects. If set to true, any requested updates to array fields will remove the specified values from the existing array. This value can be overridden by the client in the request data.

$request_data


    public
        array<string|int, mixed>
    $request_data
     = []

The request body or parameters sent by the remote client.

$request_method


    public
        string
    $request_method

The HTTP request method sent by the remote client.

$request_method_options


    public
        array<string|int, mixed>
    $request_method_options
     = []

Sets the allowed HTTP request methods for this Endpoint. For $many=true, only GET, PUT and DELETE methods can be specified here. GET will use the Model's read_all() method, PUT will use the Model's replace_all() method and DELETE will use the Model's delete_many() method. For Endpoints with $many=false, GET, POST, PATCH, and DELETE methods can be specified here. GET will use the Model's read() method, POST will use the Model's create() method. PATCH will use the Model's update() method, and DELETE will use the Model's delete() method.

$requires_auth


    public
        bool
    $requires_auth
     = true

$resource_link_set


    public
        ResourceLinkSet|null
    $resource_link_set
     = null

A ResourceLinkSet containing ResourceLinks that should always be included in the root _links for this response.

$response_types


    public
        array<string|int, mixed>
    $response_types
     = []

An array of Response classes that can be returned by this Endpoint. This array should contain the class names of the Response objects that can be returned by this Endpoint.

$restapi_settings


    public
        RESTAPISettings
    $restapi_settings

Contains the current API configuration.

$reverse


    public
        bool
    $reverse
     = false

Sets the default value for the reverse field in the request data. This value is used to control the order of the Model objects returned by this Endpoint. This value can be overridden by the client in the request data. If set to true, the Model objects in the data section of the response will be reversed.

$sort_by


    public
        string|null
    $sort_by
     = null

Sets the default value(s) for the sort_by field in the request data. This value is used to control the sorting of the Model objects returned by this Endpoint. This value can be overridden by the client in the request data. Use caution when assigning this value as it may force objects to be sorted in this order when they are written to the configuration file.

$sort_order


    public
        string
    $sort_order
     = 'SORT_ASC'

Sets the default value for the sort_order field in the request data. This value is used to control the sorting order of the Model objects returned by this Endpoint. This value can be overridden by the client in the request data. This value only takes effect when the sort_by field is also set. This value must be the name of a valid PHP sort order constant ('SORT_ASC' or 'SORT_DESC').

$tag


    public
        string
    $tag
     = ''

The OpenAPI tag applied to this Endpoint, nesting it under a specific name in the OpenAPI documentation. Defaults to the first value in the $url after /api/v2/.

$url


    public
        string
    $url
     = ''

The URL of this endpoint, used to generate a PHP file in the web path pointing back to this Endpoint class.

$client


    protected
        Auth
    $client

The \RESTAPI\Core\Auth object created by this Endpoint during API calls, contains client authentication information.

$errors


    protected
        array<string|int, mixed>
    $errors
     = []

An array to store errors encountered during API calls to this Endpoint.

__construct()

Sets values whenever the Endpoint object is crated.


    public
                    __construct() : mixed

build_endpoint_url()

Generate an endpoint for this view in the pfSense webroot.


    public
                    build_endpoint_url() : bool

Return values

bool

check_construct()

Checks for conflicting attributes during object construction.


    public
                    check_construct() : void

check_decode_content_handler_supported()

Checks if the requested decode ContentHandler is supported.


    public
                    check_decode_content_handler_supported(ContentHandler $content_handler) : void

Parameters

$content_handler : ContentHandler

check_encode_content_handler_supported()

Checks if the requested encode ContentHandler is supported.


    public
                    check_encode_content_handler_supported(ContentHandler $content_handler) : void

Parameters

$content_handler : ContentHandler

generate_pfsense_privs()

Utilizes the $url and $request_method_options properties of this Endpoint to generate pfSense privileges specific to this Endpoint class. The resulting array is then supplied to the pfSense privilege system located at /etc/inc/priv/.


    public
                    generate_pfsense_privs() : array<string|int, mixed>

Return values

array<string|int, mixed>

get_class_fqn()

Obtains the fully qualified name of the called class.


    public
                    get_class_fqn() : string

Return values

string —

The FQN for this object's class.

get_class_shortname()

Obtains the shortname of the called class.


    public
                    get_class_shortname() : string

Return values

string —

The shortname for this object's class.

get_classes_in_namespace()

Obtains all classes associated with this class's current namespace.


    public
                    get_classes_in_namespace([bool $shortnames = false ]) : array<string|int, mixed>

Parameters

$shortnames : bool = false

Return values

array<string|int, mixed> —

An array of classes currently in this object's namespace

get_endpoint_filepath()

Obtains the absolute filepath to the PHP file generated for this Endpoint.


    public
                    get_endpoint_filepath() : string

Return values

string —

The absolute filepath to this Endpoint's PHP file within the pfSense webroot.

get_pagination_resource_links()

Obtains the `prev` and `next` HATEOAS resource links for pagination use. These links supply the previous and next set of objects from the dataset.


    public
                    get_pagination_resource_links(int $limit, int $offset) : void

Parameters

$limit : int: The maximum number of Model objects to retrieve. This will be used to determine the prev and next link values.
$offset : int: The starting point in the dataset requested for pagination. This will be used to determine the prev and next link values.

log_error()

Logs an error to the syslog.


    public
            static        log_error(string $message) : void

Parameters

$message : string: The error message to write to the syslog

process_request()

Processes the API request and returns the serialized API response to send back to the client.


    public
                    process_request() : string

Return values

string —

The serialized API response to send back to the client.

response_handler()

Defines a middleware method that can be used to handle the call's Response object before it is sent back to the client. This can be used by child Endpoints to extend or override the default Response handling behavior.


    public
                    response_handler(Response $response) : Response

Parameters

$response : Response: The Response object handle before it is sent back to the client by process_request()

Return values

Response

delete()

Deletes an existing object for the assigned Model using the data submitted in a DELETE request.


    protected
                    delete() : Model|ModelSet

Return values

Model|ModelSet

get()

Obtains the object data for GET requests to this Endpoint.


    protected
                    get() : Model|ModelSet

Return values

Model|ModelSet

options()

Populates associated headers whenever an OPTIONS request is received.


    protected
        final            options() : void

patch()

Updates an existing object for the assigned Model using the data submitted in a PATCH request.


    protected
                    patch() : Model|ModelSet

Return values

Model|ModelSet

post()

Creates a new object for the assigned Model using the data submitted in a POST request.


    protected
                    post() : Model|ModelSet

Return values

Model|ModelSet

put()

Replaces all existing objects for the assigned Model using the data submitted in a PUT request.


    protected
                    put() : Model|ModelSet

Return values

Model|ModelSet

check_acl()

Checks if the client is allowed to access this Endpoint according to the REST API Access List.


    private
                    check_acl() : void

check_auth()

Checks if authentication and authorization for this Endpoint is successful. This will attempt authentication and authorization for each allowed auth method. Only one auth method needs to succeed to allow access.


    private
                    check_auth() : void

check_enabled()

Checks if the API is enabled before allowing the call.


    private
                    check_enabled() : void

check_interface_allowed()

Checks if the interface receiving the API call is allowed to answer API calls.


    private
                    check_interface_allowed() : void

check_request_data()

Checks if the API client's request data was successfully received and parsed by the API. This method populates the $this->request_data property according to the client's requested content-type.


    private
                    check_request_data() : void

check_request_method()

Check if the HTTP method requested by the API client is supported by this view.


    private
                    check_request_method() : void

get_default_privs()

Assigns the default privileges required to make API calls to this endpoint. This method will automatically populate the following properties:


    private
                    get_default_privs() : void

$this->get_privileges
$this->post_privileges
$this->patch_privileges
$this->put_privileges
$this->delete_privileges

get_method_priv_name()

Generates the privilege name necessary to execute a specific request method on this Endpoint.


    private
                    get_method_priv_name(string $method) : string

Parameters

$method : string: The HTTP method for which the resulting privilege name is intended.

Return values

string

get_required_privs()

Retrieves the necessary privileges for processing the received API call.


    private
                    get_required_privs() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of required privileges for the current API call.

set_default_help_text()

Determines the appropriate default help text for each method according to the assigned Model and Endpoint properties.


    private
                    set_default_help_text() : void

set_default_tag()

Use the endpoint's URL to determine a default OpenAPI tag for this endpoint.


    private
                    set_default_tag() : void

validate_append()

Validates the $append common control parameter for this request.


    private
                    validate_append() : void

validate_async()

Validates the $async common control parameter for this request.


    private
                    validate_async() : void

validate_endpoint_fields()

Performs validation on non-Model fields. These fields control how Models are initially obtained/constructed.


    private
                    validate_endpoint_fields() : void

validate_limit()

Validates the $limit common control parameter for this request.


    private
                    validate_limit() : void

validate_offset()

Validates the $offset common control parameter for this request.


    private
                    validate_offset() : void

validate_remove()

Validates the $remove common control parameter for this request.


    private
                    validate_remove() : void

validate_reverse()

Validates the $reverse common control parameter for this request.


    private
                    validate_reverse() : void

validate_sort_by()

Validates the $sort_by common control parameter for this request.


    private
                    validate_sort_by() : void

validate_sort_order()

Validates the $sort_order common control parameter for this request.


    private
                    validate_sort_order() : void

Endpoint in package RESTAPI uses BaseTraits

Table of Contents

Properties

Methods

Properties

$append

$async

$auth_methods

$decode_content_handlers

$delete_help_text

$delete_privileges

$deprecated

$encode_content_handlers

$get_help_text

$get_privileges

$ignore_acl

$ignore_enabled

$ignore_interfaces

$ignore_read_only

$limit

$many

$model

$model_name

$offset

$patch_help_text

$patch_privileges

$post_help_text

$post_privileges

$put_help_text

$put_privileges

$remove

$request_data

$request_method

$request_method_options

$requires_auth

$resource_link_set

$response_types

$restapi_settings

$reverse

$sort_by

$sort_order

$tag

$url

$client

$errors

Methods

__construct()

build_endpoint_url()

Tags

Return values

check_construct()

check_decode_content_handler_supported()

Parameters

Tags

check_encode_content_handler_supported()

Parameters

Tags

generate_pfsense_privs()

Tags

Return values

get_class_fqn()

Return values

get_class_shortname()

Return values

get_classes_in_namespace()

Parameters

Return values

get_endpoint_filepath()

Return values

get_pagination_resource_links()

Parameters

log_error()

Parameters

process_request()

Return values

response_handler()

Parameters

Tags

Return values

delete()

Endpoint
in package

RESTAPI

uses BaseTraits