pfSense-pkg-RESTAPI

Core

Table of Contents

Namespaces

Globals

Tools

Classes

Auth

Defines object that performs authentication and authorization for REST API Endpoints and obtains details about the authenticating client. This class is intended to be extended by child classes that define specific authentication methods.

Cache

Defines a Cache object. Cache objects are a type of Dispatcher object that is intended to fetch data from an external source and store the output to a local cache file that periodically gets updated. This is helpful when handling data that may take a long time to populate, or data that may have upstream rate limits that need to be respected.

Command

Defines an object that executes shell commands and keeps track of the output and result codes.

ContentHandler

Defines a class that is responsible for decoding request content from remote clients, and encoding response content to be sent to the remote client. Children of this class must correspond with the valid HTTP MIME type this ContentHandler is designed to interact with.

Dispatcher

Defines a Dispatcher object which defines functions that are intended to run in the background. The Dispatcher objects allows us to dynamically create a private PHP script that can be called in the background, manages the process spawn queue, and enforces background process timeouts.

Endpoint

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.

Field

Defines Model Fields and their attributes. Field's define how value should be obtained on pfSense internally, and converted into its representation form. Fields are also responsible for validation of this Field's value. This includes strict type validation, choice options, whether the value can be null or empty, etc. Field's can also be assigned custom Validator objects to add custom validation to the Field. Field's must be assigned as a properties Model objects.

Form

Defines a Form object that can be used to dynamically generate custom pfSense webConfigurator pages for a specified Model object.

Model

Defines a Model object that relates to a pfSense configuration or service. This model defines the necessary steps to validate incoming configuration and create, read, update, and/or delete data from the pfSense configuration this object relates to.

ModelSet

Defines a ModelSet object that acts as a container for multiple Model objects. This can be used to represent a set of Model objects at once. Additionally, ModelSets can be further filtered using queries.

QueryFilter

Defines a query filter that can be used to further filter a ModelSet's 'model_objects'.

ResourceLink

Defines a ResourceLink object that represents a HAL link object. These objects are primarily used by Endpoint classes to populate HAL links for objects that are related to the API call the Endpoint is serving.

ResourceLinkSet

Defines a class that allows the storage and processing of many ResourceLink objects at once.

Response

Defines the API response object. Response objects are throwable objects that contain response information such as HTTP status code, HTTP status message, API return code, error messages, and API response data. All API Error classes will originate as Response objects.

Schema

Defines a class that is used to represent a specific schema for this API. This class is intended to be extended by a child class to implement custom schema definitions using Endpoints, Models and Fields defined in this package.

TestCase

Defines a TestCase object that can be used to define child TestCase classes that test internal functionality of the API. This is needed because pfSense does not have PHPUnit readily available.

Validator

Defines a Validator object which Field objects can use to quickly validate its value.

Traits

BaseTraits

Defines a standard set of traits for all classes defined by this package. When class use this trait they will automatically inherit all resources included.

Constants

DEFAULT_CLIENT_IP_ADDRESS  = '127.0.0.1'

DEFAULT_CLIENT_USERNAME  = '(system)'

HTTP_STATUS_MESSAGES  = [100 => 'continue', 101 => 'switching protocols', 102 => 'processing', 103 => 'checkpoint', 200 => 'ok', 201 => 'created', 202 => 'accepted', 203 => 'non-authoritative information', 204 => 'no content', 205 => 'reset content', 206 => 'partial content', 207 => 'multi-status', 300 => 'multiple choices', 301 => 'moved permanently', 302 => 'found', 303 => 'see other', 304 => 'not modified', 305 => 'use proxy', 306 => 'switch proxy', 307 => 'temporary redirect', 400 => 'bad request', 401 => 'unauthorized', 402 => 'payment required', 403 => 'forbidden', 404 => 'not found', 405 => 'method not allowed', 406 => 'not acceptable', 407 => 'proxy authentication required', 408 => 'request timeout', 409 => 'conflict', 410 => 'gone', 411 => 'length required', 412 => 'precondition failed', 413 => 'request entity too large', 414 => 'request-uri too long', 415 => 'unsupported media type', 416 => 'requested range not satisfiable', 417 => 'expectation failed', 418 => "i'm a teapot", 422 => 'unprocessable entity', 423 => 'locked', 424 => 'failed dependency', 425 => 'unordered collection', 426 => 'upgrade required', 449 => 'retry with', 450 => 'blocked by windows parental controls', 500 => 'internal server error', 501 => 'not implemented', 502 => 'bad gateway', 503 => 'service unavailable', 504 => 'gateway timeout', 505 => 'http version not supported', 506 => 'variant also negotiates', 507 => 'insufficient storage', 509 => 'bandwidth limit exceeded', 510 => 'not extended']