Skip to content

Commit 217e88f

Browse files
jaredhendrickson13jaredhendrickson13
committed
docs: add more advanced documentation
1 parent 75a2cc7 commit 217e88f

File tree

3 files changed

+565
-3
lines changed

3 files changed

+565
-3
lines changed

‎docs/BUILDING_CUSTOM_ENDPOINT_CLASSES.md

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# Building Custom Endpoint Classes
2+
3+
Endpoint classes allow a specified Model class to be exposed via the REST API. Without an Endpoint class, a Model
4+
class will not be accessible via the REST API and can only be utilized locally within the package via PHP. Endpoint
5+
classes are also responsible for following:
6+
7+
- Defining the URL path for the endpoint.
8+
- Specifying which request methods are allowed.
9+
- Adding additional documentation to the endpoint's OpenAPI definition.
10+
- Generating the PHP file in the pfSense web root to expose the endpoint.
11+
12+
## Getting Started
13+
14+
Use the following class template to initialize your custom Endpoint class:
15+
16+
```php
17+
<?php
18+
19+
namespace RESTAPI\Endpoints;
20+
21+
require_once 'RESTAPI/autoloader.inc';
22+
23+
use RESTAPI\Core\Endpoint;
24+
25+
/**
26+
* TODO: Add a description of your Endpoint class here.
27+
*/
28+
class MyCustomEndpoint extends Endpoint {
29+
30+
}
31+
```
32+
33+
!!! Important
34+
Be sure to place this class file within `/usr/local/pkg/RESTAPI/Endpoints/` directory and name the file after your
35+
Model class name with a `.inc` extension.
36+
37+
## Define __construct() Method Properties
38+
39+
The `__construct` method is used to define the properties of the Endpoint class. These properties allow you to customize the
40+
behavior and attributes of the endpoint. The following properties are available:
41+
42+
### url
43+
44+
The `url` property is used to define the URL path for the endpoint. This path will be used to automatically generate the
45+
PHP file in the pfSense webroot after executing the `pfsense-restapi buildendpoints` command. The URL path should unique
46+
and begin with the `/api/v2/` prefix. This property is required.
47+
48+
Example:
49+
50+
```php
51+
$this->url = '/api/v2/my/custom/endpoint';
52+
```
53+
54+
### model_name
55+
56+
The `model_name` property is used to define the Model class that the endpoint will expose. This must be the Model
57+
class's short name, not the fully qualified class name. This property is required.
58+
59+
!!! Important
60+
The Model class set in this property must be defined within the `/usr/local/pkg/RESTAPI/Models/` directory.
61+
62+
### request_method_options
63+
64+
The `request_method_options` property is used to define which request methods are allowed for the endpoint. If a request
65+
method is not defined in this property, the endpoint will return a `405 Method Not Allowed` response when accessed with
66+
that method. This property is required.
67+
68+
Each supported request method corresponds with a the following Model class methods:
69+
70+
- A `GET` request to a `many` enabled Endpoint will call the Model's `read_all()` method.
71+
- A `GET` request to a non-`many` enabled Endpoint will call the Model's `read()` method.
72+
- A `POST` request to a non-`many` enabled Endpoint will call the Model's `create()` method.
73+
- A `PATCH` request to a non-`many` enabled Endpoint will call the Model's `update()` method.
74+
- A `DELETE` request to a non-`many` enabled Endpoint will call the Model's `delete()` method.
75+
- A `PUT` request to a `many` enabled Endpoint will call the Model's `replace_all()` method.
76+
77+
!!! Note
78+
The OPTIONS request method is automatically supported by all endpoints and does not need to be defined in the
79+
`request_method_options` property. The OPTIONS request method is used to return the allowed request methods for the
80+
endpoint. A successful options request will return a `200 OK` response with the `Allow` and `access-control-allow-methods`
81+
response header set to the allowed request methods.
82+
83+
### many
84+
85+
The `many` property is used to define if the endpoint will return a single object or many objects. This property
86+
defaults to `false`. When set to `true`, the endpoint will return an array of objects in the `data` section of the response.
87+
When set to `false`, the endpoint will return a single object in the `data` section of the response.
88+
89+
For more information on the difference between many and non-many endpoints, refer to the [Endpoint Types](ENDPOINT_TYPES.md) documentation.
90+
91+
!!! Important
92+
The `many` property can only be set to `true` if the assigned `model_name` property is a Model class that is also `many` enabled.
93+
94+
### tag
95+
96+
The `tag` property is used to define the OpenAPI tag for the endpoint. This property is optional and defaults to the
97+
first section of the URL after the `/api/v2/` prefix.
98+
99+
### requires_auth
100+
101+
The `requires_auth` property is used to define if the endpoint requires authentication and authorization. This property
102+
defaults to `true`.
103+
104+
!!! Danger
105+
Setting the `requires_auth` property to `false` will expose the endpoint to the public without any authentication or
106+
authorization checks. Do not set this property to `false` unless you are certain that the endpoint should be public.
107+
108+
### auth_methods
109+
110+
The `auth_methods` property is used to define the authentication methods that are allowed for the endpoint. This should
111+
be an array of [Auth class names](https://pfrest.org/php-docs/namespaces/restapi-auth.html) or leave empty to allow all.
112+
This property defaults to an empty array.
113+
114+
!!! Notes
115+
- This property is only applicable if the `requires_auth` property is set to `true`.
116+
- Specified class names should be the short name of the Auth class, not the fully qualified class name.
117+
118+
### ignore_read_only
119+
120+
The `ignore_read_only` property is used to define if the endpoint should ignore the REST API's read-only mode and allow
121+
non-`GET` requests even when read-only mode is enabled. This property defaults to `false`.
122+
123+
!!! Danger
124+
Setting the `ignore_read_only` property to `true` will allow the endpoint to be modified even when the REST API is
125+
in read-only mode. Do not set this property to `true` unless you are certain that the endpoint should be writable
126+
when the REST API is in read-only mode.
127+
128+
### ignore_interfaces
129+
130+
The `ignore_interfaces` property is used to define if the endpoint should ignore the REST API's allowed interfaces setting
131+
and allow all interfaces to access the endpoint. This property defaults to `false`.
132+
133+
!!! Danger
134+
Setting the `ignore_interfaces` property to `true` will allow all interfaces to access the endpoint even if the
135+
REST API's allowed interfaces setting is set. Do not set this property to `true` unless you are certain that the
136+
endpoint should be accessible from all interfaces.
137+
138+
### ignore_enabled
139+
140+
The `ignore_enabled` property is used to define if the endpoint should ignore the REST API's enabled setting and allow
141+
the endpoint to be accessed even when the REST API is disabled. This property defaults to `false`.
142+
143+
!!! Danger
144+
Setting the `ignore_enabled` property to `true` will allow the endpoint to be accessed even when the REST API is
145+
disabled. Do not set this property to `true` unless you are certain that the endpoint should be accessible when the
146+
REST API is disabled.
147+
148+
### ignore_acl
149+
150+
The `ignore_acl` property is used to define if the endpoint should ignore the REST API's ACL settings and allow all
151+
users and IPs to access the endpoint at all times. This property defaults to `false`.
152+
153+
!!! Danger
154+
Setting the `ignore_acl` property to `true` will allow all users and IPs to access the endpoint at all times. Do not
155+
set this property to `true` unless you are certain that the endpoint should be accessible to all users and IPs.
156+
157+
### get_help_text
158+
159+
The `get_help_text` property is used to overwrite the default OpenAPI description for the endpoint's GET documentation.
160+
161+
### post_help_text
162+
163+
The `post_help_text` property is used to overwrite the default OpenAPI description for the endpoint's POST documentation.
164+
165+
### patch_help_text
166+
167+
The `patch_help_text` property is used to overwrite the default OpenAPI description for the endpoint's PATCH documentation.
168+
169+
### delete_help_text
170+
171+
The `delete_help_text` property is used to overwrite the default OpenAPI description for the endpoint's DELETE documentation.
172+
173+
### put_help_text
174+
175+
The `put_help_text` property is used to overwrite the default OpenAPI description for the endpoint's PUT documentation.
176+
177+
## Example
178+
179+
Below is an example of a fully implemented Endpoint class:
180+
181+
```php
182+
<?php
183+
184+
namespace RESTAPI\Endpoints;
185+
186+
require_once 'RESTAPI/autoloader.inc';
187+
188+
use RESTAPI\Core\Endpoint;
189+
190+
/**
191+
* TODO: Add a description of your Endpoint class here.
192+
*/
193+
class MyCustomEndpoint extends Endpoint {
194+
public function __construct() {
195+
# Set required endpoint properties
196+
$this->url = '/api/v2/my/custom/endpoint';
197+
$this->model_name = 'MyCustomModel';
198+
$this->request_method_options = ['GET', 'POST', 'PATCH', 'DELETE'];
199+
$this->many = false;
200+
201+
# Set optional endpoint properties
202+
$this->tag = 'My Custom Endpoints';
203+
$this->requires_auth = true;
204+
$this->auth_methods = ['BasicAuth', "JWTAuth", "KeyAuth"];
205+
$this->ignore_read_only = false;
206+
$this->ignore_interfaces = false;
207+
$this->ignore_enabled = false;
208+
$this->ignore_acl = false;
209+
$this->get_help_text = 'Example GET description.';
210+
$this->post_help_text = 'Example POST description.';
211+
$this->patch_help_text = 'Example PATCH description.';
212+
$this->delete_help_text = 'Example DELETE description.';
213+
}
214+
}
215+
```
216+
217+
## Build the Endpoint
218+
219+
The Endpoint class is simply a blueprint or instruction set for the REST API endpoint. A PHP file must be present in the
220+
pfSense web root to actually expose the endpoint. The REST API's framework will automatically generate the PHP file for all
221+
Endpoint class URLs by running the following command:
222+
223+
```shell
224+
pfsense-restapi buildendpoints
225+
```
226+
227+
After running the command, the PHP file for the Endpoint will be generated in the pfSense web root (`/usr/local/www/`)
228+
and the endpoint will be accessible via the REST API.
229+
230+
## Generating Documentation
231+
232+
To regenerate the OpenAPI documentation for all Endpoint classes, run the following command:
233+
234+
```shell
235+
pfsense-restapi generatedocs
236+
```

0 commit comments

Comments
 (0)