[FEAT] Add (limited) API endpoint (#237)

Author: unkn0wnAPI

.env

@@ -90,10 +90,17 @@ WEBDAV_PUBLIC_DIR='/webdav/public'
 # such as /webdav/homes for instance, so that users cannot access other users' homes.
 WEBDAV_HOMES_DIR=
 
+# API
+# When this variable is not empty, the /api endpoint becomes available.
+# This endpoint allows admins to perform certain actions that are normally only available
+# via the web dashboard.
+# To generate a valid API_KEY you can use the php bin/console api:generate command.
+API_KEY=
+
 # Logging path
 # By default, it will log in the standard Symfony directory: var/log/prod.log (for production)
 # You can use /dev/null here if you want to discard logs entirely
 LOG_FILE_PATH="%kernel.logs_dir%/%kernel.environment%.log"
 
 # Trust the immediate proxy for X-Forwarded-* headers including HTTPS detection
-SYMFONY_TRUSTED_PROXIES=REMOTE_ADDR
+SYMFONY_TRUSTED_PROXIES=REMOTE_ADDR

.env.test

@@ -8,3 +8,5 @@ PANTHER_ERROR_SCREENSHOT_DIR=./var/error-screenshots
 DATABASE_URL="mysql://davis:davis@127.0.0.1:3306/davis_test?serverVersion=10.9.3-MariaDB&charset=utf8mb4"
 
 MAILER_DSN=smtp://localhost:465?encryption=ssl&auth_mode=login&username=&password=
+
+API_KEY=change_me

README.md

@@ -329,6 +329,16 @@ The main endpoint for CalDAV, WebDAV or CardDAV is at `/dav`.
 >
 > For shared hosting, the `symfony/apache-pack` is included and provides a standard `.htaccess` file in the public directory so redirections should work out of the box.
 
+## API Endpoint
+
+For user and calendar management there is an API endpoint. See [the API documentation](docs/api/README.md) for more information.
+
+> [!TIP]
+>
+> The API endpoint requires an environment variable `API_KEY` set to a secret key that you will use in the `X-Davis-API-Token` header of your requests to authenticate. You can generate it with `bin/console api:generate`
+
+## Webserver Configuration Examples
+
 ### Example Caddy 2 configuration
 
 ```

config/packages/security.yaml

@@ -8,6 +8,11 @@ security:
         dev:
             pattern: ^/(_(profiler|wdt)|css|images|js)/
             security: false
+        api_v1:
+            pattern: ^/api/v1
+            stateless: true
+            custom_authenticators:
+                - App\Security\ApiKeyAuthenticator
         main:
             lazy: true
             custom_authenticators:
@@ -16,6 +21,7 @@ security:
             logout:
                 path: app_logout
                 target: dashboard
+            
 
     access_control:
         - { path: ^/$, roles: PUBLIC_ACCESS }
@@ -24,3 +30,5 @@ security:
         - { path: ^/users, roles: ROLE_ADMIN, allow_if: "'%env(default:default_admin_auth_bypass:ADMIN_AUTH_BYPASS)%' === 'true'" }
         - { path: ^/calendars, roles: ROLE_ADMIN, allow_if: "'%env(default:default_admin_auth_bypass:ADMIN_AUTH_BYPASS)%' === 'true'" }
         - { path: ^/adressbooks, roles: ROLE_ADMIN, allow_if: "'%env(default:default_admin_auth_bypass:ADMIN_AUTH_BYPASS)%' === 'true'" }
+        - { path: ^/api/v1/health$, roles: PUBLIC_ACCESS }
+        - { path: ^/api, roles: IS_AUTHENTICATED }

config/services.yaml

@@ -78,6 +78,10 @@ services:
         arguments:
             $birthdayReminderOffset: "%birthday_reminder_offset%"
 
+    App\Security\ApiKeyAuthenticator:
+        arguments:
+            $apiKey: "%env(API_KEY)%"
+
 when@dev:
     services:
         Symfony\Component\HttpKernel\Profiler\Profiler: '@profiler'

docs/api/README.md

@@ -0,0 +1,35 @@
+# Davis API
+
+## API Version 1
+
+### Open Endpoints
+
+Open endpoints require no Authentication.
+
+* [Health](v1/health.md) : `GET /api/v1/health`
+
+### Endpoints that require Authentication
+
+Closed endpoints require a valid `X-Davis-API-Token` to be included in the header of the request. Token needs to be configured in .env file (as a environment variable `API_KEY`) and can be generated using `php bin/console api:generate` command.
+
+When `API_KEY` is not set, the API endpoints are disabled and will return a 500 error if accessed.
+
+#### User related
+
+Each endpoint displays information related to the User:
+
+* [Get Users](v1/users/all.md) : `GET /api/v1/users`
+* [Get User Details](v1/users/details.md) : `GET /api/v1/users/:username`
+
+#### Calendars related
+
+Endpoints for viewing and modifying user calendars.
+
+* [Show All User Calendars](v1/calendars/all.md) : `GET /api/v1/calendars/:username`
+* [Show User Calendar Details](v1/calendars/details.md) : `GET /api/v1/calendars/:username/:calendar_id`
+* [Create User Calendar](v1/calendars/create.md) : `POST /api/v1/calendars/:username/create`
+* [Edit User Calendar](v1/calendars/edit.md) : `POST /api/v1/calendars/:username/:calendar_id/edit`
+* [Delete User Calendar](v1/calendars/delete.md) : `POST /api/v1/calendars/:username/:calendar_id/delete`
+* [Show User Calendar Shares](v1/calendars/shares.md) : `GET /api/v1/calendars/:username/shares/:calendar_id`
+* [Share User Calendar](v1/calendars/share_add.md) : `POST /api/v1/calendars/:username/share/:calendar_id/add`
+* [Remove Share User Calendar](v1/calendars/share_remove.md) : `POST /api/v1/calendars/:username/share/:calendar_id/remove`

docs/api/v1/calendars/all.md

@@ -0,0 +1,110 @@
+# User Calendars
+
+Gets a list of all available calendars for a specific user.
+
+**URL** : `/api/v1/calendars/:username`
+
+**Method** : `GET`
+
+**Auth required** : YES
+
+**Params constraints**
+
+```
+:username -> "[username in plain text]",
+```
+
+**URL example**
+
+```json
+/api/v1/calendars/jdoe
+```
+
+## Success Response
+
+**Code** : `200 OK`
+
+**Notes**: The `events`, `notes`, and `tasks` fields return a count (number) if the component is enabled for the calendar, or `null` if the component is disabled.
+
+**Content examples**
+
+```json
+{
+	"status": "success",
+	"data": {
+		"user_calendars": [
+			{
+				"id": 1,
+				"uri": "default",
+				"displayname": "Default Calendar",
+				"events": 0,
+				"notes": null,
+				"tasks": null
+			}
+		],
+		"shared_calendars": [
+			{
+				"id": 10,
+				"uri": "c2152eb0-ada1-451f-bf33-b4a9571ec92e",
+				"displayname": "Default Calendar",
+				"events": 0,
+				"notes": null,
+				"tasks": null
+			}
+		],
+		"subscriptions": []
+	},
+	"timestamp": "2026-01-23T15:01:33+01:00"
+}
+```
+
+Shown when user does not have calendars:
+```json
+{
+	"status": "success",
+	"data": {
+		"user_calendars": [],
+		"shared_calendars": [],
+		"subscriptions": []
+	},
+	"timestamp": "2026-01-23T15:01:33+01:00"
+}
+```
+
+## Error Response
+
+**Condition** : If 'X-Davis-API-Token' is not present or mismatched in headers.
+
+**Code** : `401 UNAUTHORIZED`
+
+**Content** :
+
+```json
+{
+	"message": "No API token provided",
+	"timestamp": "2026-01-23T15:01:33+01:00"
+}
+```
+
+or
+
+```json
+{
+	"message": "Invalid API token",
+	"timestamp": "2026-01-23T15:01:33+01:00"
+}
+```
+
+**Condition** : If user is not found.
+
+**Code** : `404 NOT FOUND`
+
+**Content** :
+
+```json
+{
+	"status": "error", 
+    "message": "User Not Found",
+	"timestamp": "2026-01-23T15:01:33+01:00"
+}
+```