Skip to content

Commit b56c748

Browse files
bidi47bidi47
committed
added error reporting page
Signed-off-by: bidi <bidi@apidemia.com>
1 parent 7bd6967 commit b56c748

1 file changed

Lines changed: 125 additions & 0 deletions

File tree

‎docs/book/v5/core-features/error-reporting.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Error reporting endpoint
2+
3+
The error reporting endpoint was designed to allows the **frontend developers** of your API to report any bugs they encounter in a secure way that is fully under your control.
4+
5+
### Example case usage
6+
7+
- Frontend developed in Angular.
8+
- Frontend developer will use try-catch in the code in order to send **frontend errors** back to the API
9+
10+
## How to use it on the API side
11+
12+
Error reporting is done by sending a **POST** request to the `/error-report` endpoint, together with a **token** in the header.
13+
In the sections below we will detail how to configure error reporting in your API and how the endpoint is used by the frontend developers.
14+
15+
### Generating a token and adding it to your API config
16+
17+
First you need to generate a token for your request.
18+
This is done by using the command
19+
20+
```bash
21+
php ./bin/cli.php token:generate error-reporting
22+
```
23+
24+
The resulting token has this format `0123456789abcdef0123456789abcdef01234567`.
25+
**Note:** this example is not a valid token, it just lets you know what to look for.
26+
27+
Copy the generated token in your `config/autoload/error-handling.global.php` file.
28+
It should look similar to the example below.
29+
Your API can have multiple tokens, if needed.
30+
31+
```php
32+
return [
33+
...
34+
ErrorReportServiceInterface::class => [
35+
...
36+
'tokens' => [
37+
'0123456789abcdef0123456789abcdef01234567',
38+
],
39+
...
40+
]
41+
]
42+
```
43+
44+
### Validation mechanism
45+
46+
Behind the scenes, the API validates your configuration and lets you know if any config items prevent the submission of the error report.
47+
Below are the requirements for an application to be able to send error messages to Dotkernel API.
48+
49+
- **Server-side requirements** stored in in `config/autoload/error-handling.global.php`; note these can be set/overwritten in `config/autoload/local.php`:
50+
- All keys (`enabled`, `path`, `tokens`, `domain_whitelist` and `ip_whitelist`) must exist under `ErrorReportServiceInterface::class`.
51+
- The error reporting feature must be enabled via `ErrorReportServiceInterface::class` . `enabled` => `true`.
52+
- `ErrorReportServiceInterface::class` . `path` must have a value; if the destination file does not exist, it will be created automatically.
53+
- `ErrorReportServiceInterface::class` . `tokens` must contain at least one token.
54+
- At least one of `ErrorReportServiceInterface::class` . `domain_whitelist`/`ip_whitelist` must have at least one value.
55+
56+
**Note:** The function `checkRequest()` tries to validate the request by checking matches for `domain_whitelist` with `isMatchingDomain()` and for `ip_whitelist` with `isMatchingIpAddress()`.
57+
If both return `false`, a `ForbiddenException` is thrown and the error message does not get stored.
58+
59+
- **Application-side requirements**:
60+
- Send the `Error-Reporting-Token` header with a valid token previously stored in `config/autoload/error-handling.global.php` in the `ErrorReportServiceInterface::class` . `tokens` array.
61+
- Send the `Origin` header set to the application's URL; this is the application that send the report.
62+
63+
**Note:**
64+
65+
- The tokens under `ErrorReportServiceInterface::class` . `tokens` do not expire.
66+
- The log file stores the token value too, making it easy to identify which application sent the error message.
67+
68+
If your post passes all the checks, the message is saved for the developers.
69+
70+
#### Tips and tricks
71+
72+
If there are multiple applications that report errors to your API, you can **assign a different error reporting token** for each.
73+
The tokens support key-value pairs where
74+
75+
- The **key** is an alias relevant to the assigned application that uses it.
76+
- The **value** is the token itself.
77+
78+
Example:
79+
80+
```php
81+
// ...
82+
return [
83+
...
84+
ErrorReportServiceInterface::class => [
85+
// ...
86+
'tokens' => [
87+
'frontend' => '0123456789abcdef0123456789abcdef01234567',
88+
'admin' => '9876543210abcdef0123456789abcdef7654321',
89+
// other tokens
90+
],
91+
],
92+
];
93+
```
94+
95+
The log file will have entries similar to the below:
96+
97+
> [2024-08-29 12:47:00] [0123456789abcdef0123456789abcdef01234567] Demo error message
98+
99+
The inclusion of the token helps you identify the source of the error message.
100+
In our example, it's the application that uses the `0123456789abcdef0123456789abcdef01234567` token, which is assigned to the application `frontend`.
101+
102+
## How to use it on the Frontend side (Angular example)
103+
104+
The API developer sends a generated token to the frontend developer who will save it in their `environment.staging.ts` and/or `environment.prod.ts`.
105+
From then on, it's the frontend developer's job to set up an error reporting function similar to the one below.
106+
107+
```javascript
108+
postError(body: object): Promise<any> {
109+
return new Promise((resolve, reject) => {
110+
return this.http.post(API_ENDPOINT + 'error-report', body , {headers: new HttpHeaders({'X-Workspace': 'TOKEN', 'Access-Control-Allow-Origin': '*'})})).subscribe({
111+
next: (response: any) => {
112+
resolve(response);
113+
},
114+
error: (e: HttpErrorResponse) => reject(e),
115+
complete: () => console.info('Error on sending error'),
116+
});
117+
});
118+
}
119+
```
120+
121+
Whenever an error is found, the frontend will call `postError()` with a relevant description under `message`.
122+
123+
```javascript
124+
apiService.postError({message: 'ERROR MESSAGE'})
125+
```

0 commit comments

Comments
 (0)