Merge pull request #574 from jaredhendrickson13/next_minor

v2.2.0 Features & Fixes

.github/workflows/build.yml

@@ -86,7 +86,7 @@ jobs:
           sleep 5
 
       - name: Fetch OpenAPI schema from pfSense
-        run: curl -s -k -u admin:pfsense -X GET https://${{ matrix.PFSENSE_VERSION }}.jaredhendrickson.com/api/v2/schema > openapi-${{ matrix.PFSENSE_VERSION }}.json
+        run: curl -s -k -u admin:pfsense -X GET https://${{ matrix.PFSENSE_VERSION }}.jaredhendrickson.com/api/v2/schema/openapi > openapi-${{ matrix.PFSENSE_VERSION }}.json
 
       - name: Teardown pfSense VM
         if: "${{ always() }}"

.github/workflows/release.yml

@@ -62,7 +62,7 @@ jobs:
         with:
           files: pfSense-${{ matrix.PFSENSE_VERSION }}-pkg-RESTAPI.pkg
 
-  build_openapi:
+  build_schemas:
     runs-on: self-hosted
     needs: [release_pkg]
     steps:
@@ -92,22 +92,31 @@ jobs:
           ssh -o StrictHostKeyChecking=no -o LogLevel=quiet admin@pfSense-${{ env.DEFAULT_PFSENSE_VERSION }}-RELEASE.jaredhendrickson.com "pkg -C /dev/null add /tmp/pfSense-${{ env.DEFAULT_PFSENSE_VERSION }}-pkg-RESTAPI.pkg"
           sleep 5
 
-      - name: Fetch OpenAPI schema from pfSense
-        run: curl -s -k -u admin:pfsense -X GET https://pfSense-${{ env.DEFAULT_PFSENSE_VERSION }}-RELEASE.jaredhendrickson.com/api/v2/schema > openapi.json
+      - name: Fetch schemas from pfSense
+        run: |
+          curl -s -k -u admin:pfsense -X GET https://pfSense-${{ env.DEFAULT_PFSENSE_VERSION }}-RELEASE.jaredhendrickson.com/api/v2/schema/openapi > openapi.json
+          curl -s -k -u admin:pfsense -X GET https://pfSense-${{ env.DEFAULT_PFSENSE_VERSION }}-RELEASE.jaredhendrickson.com/api/v2/schema/graphql > schema.graphql
 
       - name: Teardown pfSense VM
         if: "${{ always() }}"
         run: |
           /usr/local/bin/VBoxManage controlvm pfSense-${{ env.DEFAULT_PFSENSE_VERSION }}-RELEASE poweroff || true
           /usr/local/bin/VBoxManage snapshot pfSense-${{ env.DEFAULT_PFSENSE_VERSION }}-RELEASE restore initial
 
-      - uses: actions/upload-artifact@v4
+      - name: Upload OpenAPI schema
+        uses: actions/upload-artifact@v4
         with:
           name: openapi.json
           path: openapi.json
 
+      - name: Upload GraphQL schema
+        uses: actions/upload-artifact@v4
+        with:
+          name: schema.graphql
+          path: schema.graphql
+
   release_docs:
-    needs: [build_openapi]
+    needs: [build_schemas]
     runs-on: ubuntu-latest
     if: ${{ !github.event.release.prerelease }}
     environment:
@@ -139,6 +148,12 @@ jobs:
           name: openapi.json
           path: openapi.json
 
+      - name: Download GraphQL schema
+        uses: actions/download-artifact@v4
+        with:
+          name: schema.graphql
+          path: schema.graphql
+
       - name: Build Swagger UI
         run: |
           mkdir -p ./www/api-docs/
@@ -166,6 +181,11 @@ jobs:
                 });
               };' > ./www/api-docs/swagger-initializer.js
 
+      - name: Write GraphQL schema
+        run: |
+          mkdir -p ./www/graphql-docs/
+          cp schema.graphql/schema.graphql ./www/graphql-docs/schema.graphql
+
       - name: Build PHP reference documentation
         run: |
           mkdir ./www/php-docs

.gitignore

@@ -4,7 +4,7 @@ tests/e2e_test_framework/__pycache__/
 .phplint-cache
 *.pyc
 venv/
-vendor/
+/vendor/
 .vagrant
 *.pkg
 node_modules

README.md

@@ -2,15 +2,19 @@
 
 [![Build](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/build.yml/badge.svg)](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/build.yml)
 [![Quality](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/quality.yml/badge.svg)](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/quality.yml)
-[![Release](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/release.yml/badge.svg)](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/release.yml)
+[![Release](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/release.yml/badge.svg)](https://github.com/jaredhendrickson13/pfsense-api/actions/workflows/release.yml)<br>
+![Downloads](https://img.shields.io/github/downloads/jaredhendrickson13/pfsense-api/total?label=Downloads)
+![License](https://img.shields.io/github/license/jaredhendrickson13/pfsense-api?label=License)
+![Docs](https://img.shields.io/website?url=https%3A%2F%2Fpfrest.org&label=Documentation)
 
-The pfSense REST API package is an unofficial, open-source REST API for pfSense CE and pfSense Plus firewalls. This package 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.
+The pfSense REST API package is an unofficial, open-source REST and GraphQL API for pfSense CE and pfSense Plus
+firewalls.It 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.
 
 ## Key Features
 
-- 100+ endpoints available for managing your firewall and associated services
+- 200+ REST endpoints available for managing your firewall and associated services
+- A GraphQL API for flexible data retrieval and mutation
 - Easy to use querying and filtering
 - Configurable security settings
 - Supports HATEOAS driven development
@@ -22,7 +26,7 @@ provide you with the information you need to configure and use the package effec
 - [Installation and Configuration](https://pfrest.org/INSTALL_AND_CONFIG/)
 - [Authentication and Authorization](https://pfrest.org/AUTHENTICATION_AND_AUTHORIZATION/)
 - [Swagger and OpenAPI](https://pfrest.org/SWAGGER_AND_OPENAPI/)
-- [Queries and Filters](https://pfrest.org/QUERIES_AND_FILTERS/)
+- [Queries, Filters, and Sorting](https://pfrest.org/QUERIES_FILTERS_AND_SORTING/)
 
 ## Quickstart
 

composer.json

@@ -1,5 +1,6 @@
 {
   "require": {
-    "firebase/php-jwt": "v6.10.*"
+    "firebase/php-jwt": "v6.10.*",
+    "webonyx/graphql-php": "^15.13"
   }
 }

docs/AUTHENTICATION_AND_AUTHORIZATION.md

@@ -84,7 +84,7 @@ curl -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxx" https://pfsense.example.
 ### Custom Authentication
 
 For advanced users, the REST API's framework allows for custom authentication methods to be added using PHP. See
-[Building Custom Authentication](./BUILDING_CUSTOM_AUTH_CLASSES.md) for more information.
+[Building Custom Authentication](BUILDING_CUSTOM_AUTH_CLASSES.md) for more information.
 
 ## Authorization
 

docs/BUILDING_CUSTOM_ENDPOINT_CLASSES.md

@@ -7,6 +7,7 @@ classes are also responsible for following:
 - Defining the URL path for the endpoint.
 - Specifying which request methods are allowed.
 - Adding additional documentation to the endpoint's OpenAPI definition.
+- Defining an associated GraphQL query/mutation type.
 - Generating the PHP file in the pfSense web root to expose the endpoint.
 
 ## Getting Started
@@ -240,10 +241,10 @@ and the endpoint will be accessible via the REST API.
 
 ## Generating Documentation
 
-To regenerate the OpenAPI documentation for all Endpoint classes, run the following command:
+To regenerate the OpenAPI and GraphQL schemas for all Endpoint classes, run the following command:
 
 ```shell
-pfsense-restapi generatedocs
+pfsense-restapi buildschemas
 ```
 
 ## Examples

docs/BUILDING_CUSTOM_MODEL_CLASSES.md

@@ -232,40 +232,40 @@ $this->unique_together_fields = ['name', 'port'];
     - The `unique_together_fields` property is only applicable when the `many` property is set to `true`.
     - The fields defined in the `unique_together_fields` property must be defined in the Model's Field objects.
 
-### sort_by_field
+### sort_by
 
-The `sort_by_field` property is used to define the field that objects of the Model will be sorted by. When this property is
-set, objects created and updated will be sorted according to the assigned field using the assigned `sort_option`.
+The `sort_by` property is used to define the fields that objects of the Model will be sorted by. When this property is
+set, objects created and updated will be sorted according to the assigned field using the assigned `sort_order`.
 
 Example:
 
 ```php
-$this->sort_by_field = 'name';
+$this->sort_by = ['name'];
 ```
 
 !!! Warning
     The use of sorting in a Model may cause IDs to be re-ordered when objects are created or updated.
 !!! Notes
-    - The `sort_by_field` property is only applicable when the `many` property is set to `true`.
-    - The field defined in the `sort_by_field` property must be defined in the Model's Field objects.
+    - The `sort_by` property is only applicable when the `many` property is set to `true`.
+    - The field defined in the `sort_by` property must be defined in the Model's Field objects.
 
-### sort_option
+### sort_order
 
-The `sort_option` property is used to define the PHP sorting option for objects of the Model. When this property is set,
+The `sort_order` property is used to define the PHP sorting option for objects of the Model. When this property is set,
 objects created and updated will be sorted according to the assigned option. For valid sorting options, refer to: For valid value options for this property, refer to the
 [PHP multi-sort function type flags](https://www.php.net/manual/en/function.array-multisort.php).
 
 Example:
 
 ```php
-$this->sort_option = SORT_ASC;
+$this->sort_order = SORT_ASC;
 ```
 
 !!! Warning
     The use of sorting in a Model may cause IDs to be re-ordered when objects are created or updated.
 !!! Notes
-    - The `sort_option` property is only applicable when the `many` property is set to `true`.
-    - The `sort_option` property is only applicable when a `sort_by_field` is defined.
+    - The `sort_order` property is only applicable when the `many` property is set to `true`.
+    - The `sort_order` property is only applicable when a `sort_by` is defined.
 
 ### subsystem
 

docs/COMMON_CONTROL_PARAMETERS.md

@@ -34,7 +34,7 @@ parameters you can use:
   immediately.
 
 !!! Tip
-    The [Swagger documentation](./SWAGGER_AND_OPENAPI.md#swagger-documentation) will indicate if an endpoint applies
+    The [Swagger documentation](SWAGGER_AND_OPENAPI.md#swagger-documentation) will indicate if an endpoint applies
     changes immediately or requires a separate apply call. If an endpoint applies changes immediately, this parameter
     will have no effect.
 
@@ -75,6 +75,16 @@ parameters you can use:
   submitted in your request will be removed from the existing array values. This is useful when you want to remove
   specific values from an array field without needing to retrieve the existing values first.
 
+!!! Warning
+    If you set this parameter to `true`, it will apply to all array fields. You can't choose to remove to some array
+    fields and replace others at the same time. To work around this, first make a request with the data for the fields
+    you want to remove from. Then, make another request for the fields you want to replace.
+
+!!! Notes
+  - This parameter is only available for `PATCH` requests.
+  - This parameter is only applicable to array fields.
+  - If the submitted array values match the existing array values exactly, the API will not make any changes to that field to avoid removing all values unintentionally.
+
 ## reverse
 
 - Type: Boolean
@@ -84,5 +94,22 @@ parameters you can use:
   looking for an object near the end of the list. Additionally, it is helpful for time-sorted objects, such as logs,
   where you may want to view the most recent entries first.
 
-!!! Note
-    This parameter is only available for `GET` requests to [plural endpoints](ENDPOINT_TYPES.md#plural-many-endpoints).
+## sort_by
+
+- Type: String or Array
+- Default: _Defaults to the primary sort attribute for the endpoint, typically `null`._
+- Description: This parameters allows you to select the fields to use to sort the objects related to the endpoint. The
+  behavior of this parameter varies based on the request method and endpoint type. Refer to the 
+  [Sorting](QUERIES_FILTERS_AND_SORTING.md#sorting) section for more information.
+
+## sort_order
+
+- Type: String
+- Default: `SORT_ASC`
+- Choices:
+    - `SORT_ASC`
+    - `SORT_DESC`
+- Description: This parameter allows you to control the order in which the objects are sorted. The default value is
+  `SORT_ASC` which sorts the objects in ascending order. Setting this parameter to `SORT_DESC` will sort the objects in
+  descending order. The behavior of this parameter varies based on the request method and endpoint type. Refer to the
+  [Sorting](QUERIES_FILTERS_AND_SORTING.md#sorting) section for more information.

docs/CONTRIBUTING.md

@@ -47,7 +47,7 @@ While not a PHP namespace, this directory contains common resources and tools us
 
 Contains the cache files for the REST API package. Cache files are typically JSON datasets populated by [\RESTAPI\Core\Cache](https://pfrest.org/php-docs/classes/RESTAPI-Core-Cache.html) child classes and are refreshed on the schedule defined in the class.
 
-#### includes/
+#### vendor/
 
 Contains additional PHP libraries and classes required by the REST API package. Because pfSense does not include a PHP package manager, these libraries are installed to this directory via composer when the package is built.
 
@@ -319,5 +319,18 @@ REST API > Documentation'. If you make changes to the package's codebase, you ca
 to include the changes by running the following command on your pfSense instance:
 
 ```bash
-pfsense-restapi generatedocs
+pfsense-restapi buildschemas
+```
+
+### GraphQL
+
+The GraphQL schema provides accurate documentation for the various GraphQL queries and mutations available in the package.
+The GraphQL schema is automatically generated by the package using properties defined in Endpoint, Models, and Fields.
+Each of these classes have properties that map to GraphQL properties and are used to generate the GraphQL schema. The
+GraphQL schema is automatically generated when the package is initially installed and the GraphQL schema is accessible
+at /api/v2/graphql/schema. If you make changes to the package's codebase, you can regenerate the GraphQL schema to include
+the changes by running the following command on your pfSense instance:
+
+```bash
+pfsense-restapi buildschemas
 ```