NextCloud Calendar Manage API

Overview

This project provides a REST API for manipulating NextCloud calendars using Flask, allowing you to retrieve, add, and delete NextCloud calendar events and check for the existence of events via the API. It is intended to be called from a script to be used to automatically add events to the calendar on a regular basis.

Quick Start

Option1: Running with Python

Install the required packages:

pip install -r requirements.txt

Set environment variables:

• NEXTCLOUD_URL: Your NextCloud URL.
• NEXTCLOUD_USERNAME: Your NextCloud username.
• NEXTCLOUD_PASSWORD: Your NextCloud password.
• VERIFY_SSL: Set to True to validate SSL certificates (if using a trusted certificate).

Example:

export NEXTCLOUD_URL='https://your_nextcloud_domain/remote.php/dav'
export NEXTCLOUD_USERNAME='your_username'
export NEXTCLOUD_PASSWORD='your_password'
export VERIFY_SSL='False'

Run the Flask application:

python app.py

Option2: Running with Docker

Build the Docker image:

docker build -t nextcloud-calendar-api .

Run the Docker container:

docker run -d -p 5000:5000 \
  -e NEXTCLOUD_URL='https://<your_nextcloud_domain>/remote.php/dav' \
  -e NEXTCLOUD_USERNAME='<your_nextcloud_username>' \
  -e NEXTCLOUD_PASSWORD='<your_nextcloud_password>' \
  -e VERIFY_SSL='False' \
  nextcloud-flask-api

The API will be accessible at http://localhost:5000.

API Reference

1. Get Calendars

• Endpoint: /calendars
• Method: GET
• Description: Retrieves a list of all calendars associated with the user.
• Response:
  • Success (200):

    {
      "calendars": ["Calendar1", "Calendar2"]
    }

  • Error (500):

    {
      "error": "Failed to retrieve calendars"
    }

2. Add Event

• Endpoint: /add_event
• Method: POST
• Description: Adds a new event to a specific calendar.
• Request Body:

  {
    "calendar_name": "Calendar1",
    "start_time": "2024-10-05T09:00:00",
    "end_time": "2024-10-05T10:00:00",
    "summary": "Meeting",
    "description": "study session",
    "timezone": "Asia/Tokyo"
  }

• Response:
  • Success (200):

    {
      "message": "Event added to Calendar1"
    }

  • Error (400):

    {
      "error": "Invalid event data"
    }

  • Error (500):

    {
      "error": "Failed to add event"
    }

3.Delete Event

• Endpoint: /delete_event
• Method: DELETE
• Description: Deletes an event from a specific calendar.
• Request Body:

  {
    "calendar_name": "Calendar1",
    "summary": "Meeting"
  }

• Response:
  • Success (200):

    {
      "message": "Event 'Meeting' deleted from Calendar1"
    }

  • Error (400):

    {
      "error": "Failed to delete event"
    }

4. Get Events

• Endpoint: /events
• Method: GET
• Description: Retrieves all events from a specific calendar.
• Query Parameters:
  • calendar_name: The name of the calendar.
• Response:
  • Success (200):

    {
      "events": ["Event1", "Event2"]
    }

  • Error (400):

    {
      "error": "Failed to retrieve events"
    }

5. Event Exists

• Endpoint: /event_exists
• Method: GET
• Description: Checks if a specific event exists in a calendar.
• Query Parameters:
  • calendar_name: The name of the calendar.
  • summary: The summary of the event.
• Response:
  • Success (200):

    {
      "exists": true
    }

  • Error (400):

    {
      "error": "calendar_name and summary are required"
    }

  • Error (500):

    {
      "error": "Failed to check if event exists"
    }