pfSense-pkg-RESTAPI

Endpoint
in package
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.

Table of Contents

Properties

$append  : bool
$async  : bool
$auth_methods  : array<string|int, mixed>
$delete_help_text  : string
$delete_privileges  : array<string|int, mixed>
$deprecated  : bool
$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
$restapi_settings  : RESTAPISettings
$reverse  : bool
$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.
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.
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.

Properties

$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.

$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.

$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.

$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.

$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.

Methods

__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
Tags
returns

bool Returns true if the endpoint was successfully built, returns false otherwise.

Return values
bool

check_construct()

Checks for conflicting attributes during object construction.

public check_construct() : void

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>
Tags
returns

array The pfSense priv list entry array corresponding to the privileges of this Endpoint.

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.

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

options()

Populates associated headers whenever an OPTIONS request is received.

protected final options() : void

check_acl()

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

private check_acl() : void
Tags
throws
ForbiddenError

When the client is not allowed to access this Endpoint.

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.

Tags
returns

string The complete pfSense privilege name needed to authorize API requests to this endpoint using the specified $method.

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
Tags
note

If the append field was not provided in the request data, the request will default to the Endpoint's assigned $append property value.

throws
ValidationError

When the append field is not a boolean.

validate_async()

Validates the $async common control parameter for this request.

private validate_async() : void
Tags
note

If the async field was not provided in the request data, the request will default to the Endpoint's assigned $async property value.

throws
ValidationError

When the async field is not a boolean.

validate_endpoint_fields()

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

private validate_endpoint_fields() : void
Tags
throws
ValidationError

When one or more Endpoint releated fields fail validation.

validate_limit()

Validates the $limit common control parameter for this request.

private validate_limit() : void
Tags
note

If the limit field was not provided in the request data, the request will default to the Endpoint's assigned $limit property value.

throws
ValidationError

When the limit field is not an integer.

validate_offset()

Validates the $offset common control parameter for this request.

private validate_offset() : void
Tags
note

If the offset field was not provided in the request data, the request will default to the Endpoint's assigned $offset property value.

throws
ValidationError

When the offset field is not an integer.

validate_remove()

Validates the $remove common control parameter for this request.

private validate_remove() : void
Tags
note

If the remove field was not provided in the request data, the request will default to the Endpoint's assigned $remove property value.

throws
ValidationError

When the remove field is not a boolean.

validate_reverse()

Validates the $reverse common control parameter for this request.

private validate_reverse() : void
Tags
note

If the reverse field was not provided in the request data, the request will default to the Endpoint's assigned $reverse property value.

throws
ValidationError

When the reverse field is not a boolean.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results