docs: enhance mkdocs pages

Author: jaredhendrickson13

docs/BUILDING_CUSTOM_AUTH_CLASSES.md

@@ -1,5 +1,9 @@
 # Building Custom Authentication Classes
 
+!!! Danger
+    This feature is intended for advanced use cases only. Incorrectly implemented custom authentication classes can lead to
+    significant security vulnerabilities.
+
 For advanced users, the REST API's framework allows for custom authentication methods to be added using PHP. To add a custom
 authentication method, extend the `\RESTAPI\Core\Auth` class and implement the `_authenticate` method. This method simply
 needs to return a boolean value indicating if the user is authenticated or not. Below is an example of a custom Auth class:

docs/CONTENT_AND_ACCEPT_TYPES.md

@@ -0,0 +1,29 @@
+# Content and Accept Types
+
+The REST API has been designed to support multiple content and accept types to allow for flexibility in the data being sent and received. This document outlines the content and accept types supported by the REST API.
+
+## Content Types
+
+Content types are used to specify the format of the data being sent in your request. You must specify the content type in the `Content-Type` header of your request. The REST API supports the following content types:
+
+### application/json
+- MIME Type: `application/json`
+- Description: Use this content type to send JSON data in the body of your request. The data should be formatted as a JSON object or array.
+- Example: ```{"key": "value"}```
+
+### application/x-www-form-urlencoded
+- MIME Type: `application/x-www-form-urlencoded`
+- Description: Use this content type to send form data in the URL of the request. The data is sent as key-value pairs separated by an ampersand `&`.
+- Example: ```https://pfsense.example.com?key=value&key2=value2```
+
+!!! Warning
+    The `application/x-www-form-urlencoded` content-type is not fully suitable for requests other than `GET` and `DELETE` requests. It is recommended to use `application/json` for all other request types.
+
+## Accept Types
+
+Accept types are used to specify the format of the data you would like to receive in the response. You can specify the accept type in the `Accept` header of your request, or the response will default to `application/json`. The REST API supports the following accept types:
+
+### application/json
+- MIME Type: `application/json`
+- Description: Use this accept type to receive JSON data in the response. The data will be formatted as a JSON object or array.
+- Example: ```{"key": "value"}```

docs/CONTRIBUTING.md

@@ -33,8 +33,6 @@ The project utilizes PHP namespaces to organize its codebase.
 
 Below is a brief overview of the project's structure:
 
-Certainly! Here is the content separated into distinct sections:
-
 ### RESTAPI/
 
 The main namespace for the REST API package. All classes and interfaces are organized under this namespace or a child

docs/DISPATCHERS_AND_CACHING.md

@@ -14,7 +14,7 @@ to wait for the operation to complete. A list of all current Dispatcher classes
 [PHP reference](https://pfrest.org/php-docs/namespaces/restapi-dispatchers.html).
 
 !!! Note
-    You can bypass the Dispatcher spawning processes in the background by setting the ['async' control parameter](https://pfrest.org/COMMON_CONTROL_PARAMETERS/#async)
+    You can bypass the Dispatcher process spawning in the background in your API calls by setting the ['async' control parameter](https://pfrest.org/COMMON_CONTROL_PARAMETERS/#async)
     to `false`. This will cause the Dispatcher to execute the operation within the main process and wait for the operation to
     complete before returning a response.
 

docs/INSTALL_AND_CONFIG.md

@@ -8,13 +8,13 @@ Overall, the REST API package is designed to be as lightweight as possible and s
 run pfSense. It's recommended to follow Netgate's [minimum hardware requirements](https://docs.netgate.com/pfsense/en/latest/hardware/minimum-requirements.html).
 
 !!! Warning
-    While the package should behave identically on architectures other than amd64, it has only been tested on amd64
+    While the package should behave identically on architectures other than amd64, automated testing only covers amd64
     builds of pfSense. Support on other architectures is not guaranteed.
 
 ### Supported pfSense versions
 
-- pfSense CE 2.7.2 (amd64)
-- pfSense Plus 24.03 (amd64)
+- pfSense CE 2.7.2
+- pfSense Plus 24.03
 
 !!! Tip
     Don't see your version of pfSense? Older versions of pfSense may be supported by older versions of this package.
@@ -36,11 +36,11 @@ pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/re
 
 !!! Important
     When updating pfSense, **you must reinstall this package afterward** as pfSense removes unofficial packages during
-    system updates.
+    system updates and has no way to automatically reinstall them.
 
 ## Configuring the package
 
-The REST API is designed to be used out of the box. However, there are a number of configuration options available to
+The REST API is designed to be ready to use out of the box. However, there are a number of configuration options available to
 you to customize the API to your needs. The REST API settings can be configured in pfSense webConfigurator under
 'System' -> 'REST API' or via `PATCH` request to the [/api/v2/system/restapi/settings](https://pfrest.org/api-docs/#/SYSTEM/patchSystemRESTAPISettingsEndpoint)
 endpoint.

docs/LIMITATIONS_AND_FAQS.md

@@ -6,5 +6,36 @@ Keep the following limitations in mind when using this API:
 
 - pfSense's XML configuration was not designed for large scale concurrency. It may be necessary to delay API calls to
   prevent unexpected behavior, such as configuration overwrites.
+- While the REST API contains controls that should help improve scalability and resource management in comparison to 
+  the webConfigurator, it is still recommended to use the API with caution on large datasets.
 
 ## Frequently Asked Questions
+
+### Why is this package not an official pfSense package?
+
+I'd love for it to be an official package! A few years back, Netgate opened a friendly dialogue about the
+possibility of making this package official. There was some back and forth about the direction of the package and pfSense
+itself. Since then, I have been working on addressing most of the items that were brought up during the discussions but
+it seems interest has waned on Netgate's side. I am still open to the idea of making this an official package and would
+still love to work with Netgate to make that happen.
+
+For now, I will say there are still some benefits to this package being unofficial. It allows for more rapid development and
+more flexibility in the direction of the package. It also allows for more community involvement in the development of the
+package. It also ensures the package remains free and open-source.
+
+### Why are the v1 and v2 APIs separate packages?
+
+There are three primary reasons it was decided to create a new package for the v2 API:
+
+1. **Backwards Compatibility**: It was realized early on that the v2 API would require a significant amount of changes to
+the underlying codebase. This would have made it difficult to maintain backwards compatibility with the v1 API with both 
+codebases in one package. Instead, it was decided to create a new package for the v2 API to allow for a clean break from
+the v1 API and still allow both packages to be installed concurrently for users who still require v1.
+2. **Namespaces**: v1 notably lacked the use of namespaces for the underlying framework which led to a number of conflicts
+when trying to implement v2. v2 was designed from the ground up with namespaces in mind to prevent these conflicts and
+allow major revisions to be included in the same package going forward.
+3. **Accuracy**: The v1 codebase was a brute force attempt at creating an API for pfSense. Initially it was not 
+designed to with RESTful principles. The v2 API was designed from the ground up with RESTful principles in mind and
+is a much more accurate representation of a RESTful API, therfor it was decided to create a new package to reflect this
+change while also differentiating it from Netgate's purported RESTCONF plans.
+

docs/QUERIES_AND_FILTERS.md

@@ -6,8 +6,11 @@ Queries can be used to filter the data that is returned from the API based on sp
 query parameters in the URL and are formatted as `key=value`. Multiple queries can be passed in a single request by
 separating them with an ampersand `&`.
 
-!!! Note
-    Queries are only available for `GET` requests to [plural endpoints](./ENDPOINT_TYPES.md#plural-many-endpoints).
+!!! Important
+    - Queries are only available for `GET` requests to [plural endpoints](./ENDPOINT_TYPES.md#plural-many-endpoints).
+    - While it is not standard HTTP practice, the REST API will allow you to pass query parameters in the request body
+    for `GET` requests as long as the correct Content-Type header is set. This may be useful when you need to force
+    the type of a query parameter or when the query parameter is too long to fit in the URL.
 
 ## Query Filters
 

docs/WORKING_WITH_HATEOAS.md

@@ -14,7 +14,8 @@ easily navigate the API and discover available actions and resources related to
       endpoint's `hateoas` field.
 !!! Important
     Enabling HATEOAS can greatly increase the size of API responses as additional links are included in the response data;
-    which may also impact performance on large datasets.
+    which may also impact performance on large datasets. It is strongly recommended to only enable HATEOAS when needed and
+    to use [pagination](./QUERIES_AND_FILTERS.md#pagination) to limit the amount of data returned in a single request.
 
 ### Link types
 

docs/index.md

@@ -1,6 +1,6 @@
 # pfSense REST API
 
-The pfSense REST API package is an unofficial, open-source REST API for pfSense CE and pfSense Plus firewalls. This package is
+The pfSense REST API package is an unofficial, open-source REST API for pfSense CE and pfSense Plus firewalls that is
 designed to be light-weight, fast, and easy to use. This guide will help you get started with the REST API package and
 provide you with the information you need to configure and use the package effectively.
 
@@ -10,6 +10,10 @@ provide you with the information you need to configure and use the package effec
     'System' -> 'REST API' -> 'Documentation'. Alternatively, a simplified version of the Swagger documentation is 
     available [here](https://pfrest.org/api-docs/).
 
+!!! Note
+    These docs are only applicable to the REST API v2 package and later. If you are using the legacy v1 package, please
+    refer to the docs on the [legacy branch](https://github.com/jaredhendrickson13/pfsense-api/tree/legacy).
+
 ## Key Features
 
 - 100+ endpoints available for managing your firewall and associated services

mkdocs.yml

@@ -6,6 +6,7 @@ nav:
       - Swagger & OpenAPI: SWAGGER_AND_OPENAPI.md
       - Endpoint Types: ENDPOINT_TYPES.md
       - Authentication & Authorization: AUTHENTICATION_AND_AUTHORIZATION.md
+      - Content & Accept Types: CONTENT_AND_ACCEPT_TYPES.md
       - Queries & Filters: QUERIES_AND_FILTERS.md
       - Working with Object IDs: WORKING_WITH_OBJECT_IDS.md
       - Working with HATEOAS: WORKING_WITH_HATEOAS.md