[FEAT] Add (limited) API endpoint #237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

unkn0wnAPI wants to merge 60 commits into tchapi:main from unkn0wnAPI:feature_api

+2,520 −4

.env

-Original file line number
+Diff line change
@@ Expand Up / @@ -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

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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

-Original file line number
+Diff line change
@@ Expand Up @@
     >
     > 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
     ```
@@ Expand Down @@

config/packages/security.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -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:
@@ Expand All / @@ -16,6 +21,7 @@ security: @@
                 logout:
                     path: app_logout
                     target: dashboard
         access_control:
             - { path: ^/$, roles: PUBLIC_ACCESS }
@@ Expand All / @@ -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

-Original file line number
+Diff line change
@@ Expand Up / @@ -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'
@@ Expand Down @@

docs/api/README.md

-Original file line number
+Diff line change
@@ -0,0 +1,34 @@
+    # 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`
+    * [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

-Original file line number
+Diff line change
@@ -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"
+    }
+    ```

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[FEAT] Add (limited) API endpoint #237

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

[FEAT] Add (limited) API endpoint #237

Are you sure you want to change the base?

[FEAT] Add (limited) API endpoint #237

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!