2026-05-10 19:14:24 +00:00
1 changed files with 236 additions and 15 deletions
@@ -1,43 +1,264 @@
 # MokoDPCalendarAPI

-Joomla Web Services plugin exposing DPCalendar events, calendars, and locations via REST API
+Joomla Web Services plugin exposing **18 REST endpoints** for DPCalendar events, calendars, locations, bookings, and tickets.

-![Language](https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-MokoDPCalendarAPI-blue?style=flat-square)
+![PHP 8.1+](https://img.shields.io/badge/PHP-8.1%2B-777BB4?style=flat-square&logo=php&logoColor=white) ![Joomla 5.x/6.x](https://img.shields.io/badge/Joomla-5.x%20%7C%206.x-5091CD?style=flat-square&logo=joomla&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Version](https://img.shields.io/badge/version-03.01.00-blue?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-MokoDPCalendarAPI-blue?style=flat-square)

+---

-Joomla Web Services plugin exposing DPCalendar events, calendars, and locations via REST API
+## Features

-| Field | Value |
+- **18 REST endpoints** across 5 resources (events, calendars, locations, bookings, tickets)
+- **CRUD operations** for events including bulk creation
+- **iCal export** for events and calendars (`.ics` format)
+- **Recurring event expansion** -- RRULE processing with EXDATE support
+- **Pagination** with `limit`/`offset` (max 100 per page)
+- **Sorting** by 6 fields with ascending/descending order
+- **Filtering** by date range, category, search term, featured, access level, language
+- **Field selection** -- request only the fields you need
+- **Location expansion** -- inline location data with events via `expand=locations`
+- **ETag caching** with HTTP 304 Not Modified support
+- **CORS headers** for cross-origin requests
+
+---
+
+## Requirements
+
+| Requirement | Version |
 |---|---|
-| **Language** | PHP |
-| **License** | GPL-3.0-or-later |
-| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI) |
+| **PHP** | 8.1+ |
+| **Joomla** | 5.x or 6.x |
+| **DPCalendar** | Required (component must be installed) |

 ---

-## Guides
+## Installation

-| Page | Description |
-|---|---|
-| [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/wiki/INSTALLATION) | - Joomla 5.x or 6.x |
+1. Download the latest release package from [Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/releases)
+2. In Joomla Admin, go to **System > Install > Extensions**
+3. Upload the `.zip` package
+4. Navigate to **System > Plugins** and search for `"Web Services - DPCalendar"`
+5. Enable the plugin
+
+See the [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/wiki/INSTALLATION) wiki page for detailed instructions.

 ---

-> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)
+## Authentication
+
+All API requests require a Joomla API token passed via the `Authorization` header:
+
+```
+Authorization: Bearer <your-joomla-api-token>
+```
+
+Generate a token in **Joomla Admin > Users > Manage > [User] > Joomla API Token tab**.

 ---

+## Endpoints

+Base path: `/api/index.php/v1`
+
+### Events (8 endpoints)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/dpcalendar/events` | List events with filtering, sorting, pagination |
+| `GET` | `/dpcalendar/events/{id}` | Get a single event by ID |
+| `POST` | `/dpcalendar/events` | Create a new event |
+| `POST` | `/dpcalendar/events/bulk` | Bulk create multiple events |
+| `PATCH` | `/dpcalendar/events/{id}` | Update an existing event |
+| `DELETE` | `/dpcalendar/events/{id}` | Trash an event (soft delete) |
+| `GET` | `/dpcalendar/events/{id}/ical` | Export event as iCal (.ics) |
+| `GET` | `/dpcalendar/events/{id}/occurrences` | List occurrences of a recurring event |
+
+### Calendars (3 endpoints)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/dpcalendar/calendars` | List all calendars |
+| `GET` | `/dpcalendar/calendars/{id}` | Get a single calendar by ID |
+| `GET` | `/dpcalendar/calendars/{id}/ical` | Export calendar as iCal (.ics) |
+
+### Locations (2 endpoints)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/dpcalendar/locations` | List all locations |
+| `GET` | `/dpcalendar/locations/{id}` | Get a single location by ID |
+
+### Bookings (2 endpoints)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/dpcalendar/bookings` | List all bookings |
+| `GET` | `/dpcalendar/bookings/{id}` | Get a single booking (with tickets) |
+
+### Tickets (2 endpoints)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/dpcalendar/tickets` | List all tickets |
+| `GET` | `/dpcalendar/tickets/{id}` | Get a single ticket |
+
+---
+
+## Query Parameters
+
+### Pagination
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `page[limit]` | integer | 20 | Results per page (max 100) |
+| `page[offset]` | integer | 0 | Number of results to skip |
+
+### Sorting
+
+| Parameter | Type | Description |
+|---|---|---|
+| `sort` | string | Sort field. Prefix with `-` for descending. |
+
+**Supported sort fields:** `id`, `title`, `start_date`, `end_date`, `catid`, `created`
+
+Example: `?sort=-start_date` (newest first)
+
+### Filtering
+
+| Parameter | Type | Description |
+|---|---|---|
+| `filter[search]` | string | Search events by title or description |
+| `filter[start_date]` | string | Events starting on or after this date (ISO 8601) |
+| `filter[end_date]` | string | Events ending on or before this date (ISO 8601) |
+| `filter[catid]` | integer | Filter by calendar/category ID |
+| `filter[featured]` | integer | `1` = featured only, `0` = non-featured only |
+| `filter[access]` | integer | Filter by Joomla access level |
+| `filter[language]` | string | Filter by language tag (e.g., `en-GB`) |
+
+### Field Selection
+
+| Parameter | Type | Description |
+|---|---|---|
+| `fields[events]` | string | Comma-separated list of fields to return |
+
+Example: `?fields[events]=id,title,start_date,end_date`
+
+### Expansion
+
+| Parameter | Type | Description |
+|---|---|---|
+| `expand` | string | Include related data. Supported: `locations` |
+
+---
+
+## Examples
+
+### List upcoming events
+
+```bash
+curl -s \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: application/vnd.api+json" \
+  "https://example.com/api/index.php/v1/dpcalendar/events?filter[start_date]=2026-01-01&sort=start_date&page[limit]=10"
+```
+
+### Get a single event
+
+```bash
+curl -s \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: application/vnd.api+json" \
+  "https://example.com/api/index.php/v1/dpcalendar/events/42"
+```
+
+### Create an event
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/vnd.api+json" \
+  -d '{
+    "title": "Monthly Meetup",
+    "catid": 8,
+    "start_date": "2026-06-15 18:00:00",
+    "end_date": "2026-06-15 20:00:00",
+    "description": "<p>Join us for the monthly meetup!</p>"
+  }' \
+  "https://example.com/api/index.php/v1/dpcalendar/events"
+```
+
+### Bulk create events
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/vnd.api+json" \
+  -d '[
+    {"title": "Event A", "catid": 8, "start_date": "2026-07-01 10:00:00", "end_date": "2026-07-01 12:00:00"},
+    {"title": "Event B", "catid": 8, "start_date": "2026-07-02 10:00:00", "end_date": "2026-07-02 12:00:00"}
+  ]' \
+  "https://example.com/api/index.php/v1/dpcalendar/events/bulk"
+```
+
+### Export calendar as iCal
+
+```bash
+curl -s \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: text/calendar" \
+  "https://example.com/api/index.php/v1/dpcalendar/calendars/8/ical"
+```
+
+### Get recurring event occurrences
+
+```bash
+curl -s \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: application/vnd.api+json" \
+  "https://example.com/api/index.php/v1/dpcalendar/events/42/occurrences"
+```
+
+### List events with location expansion
+
+```bash
+curl -s \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: application/vnd.api+json" \
+  "https://example.com/api/index.php/v1/dpcalendar/events?expand=locations"
+```
+
+### ETag caching (conditional request)
+
+```bash
+# First request -- note the ETag in response headers
+curl -sI \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: application/vnd.api+json" \
+  "https://example.com/api/index.php/v1/dpcalendar/events"
+
+# Subsequent request -- returns 304 if unchanged
+curl -s \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: application/vnd.api+json" \
+  -H 'If-None-Match: "etag-value-from-previous-response"' \
+  "https://example.com/api/index.php/v1/dpcalendar/events"
+```

 ---

 ## Documentation

-Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/wiki).
+Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/wiki), including:

-## Contributing
+| Page | Description |
+|---|---|
+| [Home](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/wiki/Home) | Overview and quick reference |
+| [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/wiki/INSTALLATION) | Installation guide for Joomla 5.x/6.x |
+| [API-Reference](https://git.mokoconsulting.tech/MokoConsulting/MokoDPCalendarAPI/wiki/API-Reference) | Complete endpoint documentation |

-See the wiki for development guidelines and contribution instructions.
+---

 ## License