[FEAT] Add (limited) API endpoint

[unkn0wnAPI]

Description

This PR adds an API endpoint that allows admins to perform the following user/calendar management tasks, which are normally only available via the admin dashboard:

• Getting a list of all users added to Davis
• Getting details of a specific user account
• Getting a list of all calendars owned by a specific user
• Getting details about a specific calendar owned by a specific user
• Getting a list of users that have access to another user's calendar (Shared Calendar)
• Sharing a user's calendar with a specific user (with write access enabled/disabled)
• Removing access to a user's calendar from a specific user

Additionally, this PR would include:

• Markdown API documentation with examples
• Brief information about the endpoint in the main README.md file
• A new Symfony command that can generate an API key

Reasoning for this PR

I wanted to centralize and automate calendar management in my environment. Rather than emulating browser clicks, I created an API endpoint that allows admins to perform basic tasks via API requests.

The logic for specific endpoints is based on existing code in this project and was designed to mimic its output and functionality, with additional security checks. I made the API endpoint paths match the paths I found using console debug:router to make it easier to understand what each route does. Since I use Davis with OpenLDAP, I skipped the logic regarding user creation, removal, etc.

Source / References

Logic found in /src/Controller/*.php files
Symfony Command Creation

[tchapi]

Hi @unkn0wnAPI 👋🏼

First of all, thanks for your interest and the work you put in adding this feature.

I need to get my head around it and I lack some time right now, but I'll probably be able to dedicate more focus in the coming week. Still, I've added a few comments on the code so we can move forward.

Apart from them, an important point would be on the API authentication. I'd rather use a standard Symfony protocol than custom checks in the controller (maybe JSON-login, tied to the admin user or to each user, or a custom authenticator that indeed uses an API-key header).

Happy to discuss, and thanks again!

[unkn0wnAPI]

Hi,
Thank you for the message and for this project.

I will try my best to go over the code in the next few days (midterms are approaching, which limits my free time). In the meantime, I attempted to address most of the code review questions.

Regarding API authentication, I would need to explore the options available in Symfony, as I have not worked with Symfony Custom/JSON Auth before. However, I believe this functionality should be restricted to administrators, since most of the API functionality revolves around admin tasks (most users only interact with their CalDav-supporting application of choice).

Both JSON Login and API Key authentication seem promising, depending on the implementation:

• JSON Login allows for token expiration.
• Including the API Key in the request body could simplify the API flow in applications by removing the need to check for reauthentication with the endpoint.

Do you have a preferred approach or any suggestions regarding API authentication?

[tchapi]

I will try my best to go over the code in the next few days (midterms are approaching, which limits my free time)

Absolutely no pressure. I myself have a tight planning.

However, I believe this functionality should be restricted to administrators, since most of the API functionality revolves around admin tasks (most users only interact with their CalDav-supporting application of choice).

Agreed

Do you have a preferred approach or any suggestions regarding API authentication?

I guess an API key in the request (headers probably) — just like you initially envisioned — but embedded in a proper Symfony class / process should fit the use case quite well.

BR

[unkn0wnAPI]

Hi,
It took some time, but I’ve migrated the API authentication to a custom Symfony Authenticator. It works the same as before (API key verification), but the logic is now handled by Symfony Security instead of the API class itself.

As part of this change, I fixed and refactored the existing API endpoints. For example, calendar details now indicate whether a calendar supports tasks, notes, and events. I’ve also moved the API endpoints from /api/* to /api/v1/* to allow room for future breaking changes or additions.

Additionally, I added two new endpoints that allow admins to:

1. Create a new calendar for a user (Name, Description and tasks/events/notes support can be defined)
2. Edit existing user calendar details (e.g., name, description, or task/event/note support)

The API documentation has been updated accordingly.

[tchapi]

Thanks again for your work; it's clear, well-documented and seems to fit the bill quite right. Two comments below that are of importance.

Last thing we need is some basic tests of the ApiController, if you don't mind (simple use cases should be enough).

[unkn0wnAPI]

Hi,
I’ve updated the sections mentioned in the code report comments. As for the ApiController tests, I’ll try to write them this week.