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
PHP	8.1+
Joomla	5.x or 6.x
DPCalendar	Required (component must be installed)

Installation

Download the latest release package from Releases
In Joomla Admin, go to System > Install > Extensions
Upload the .zip package
Navigate to System > Plugins and search for "Web Services - DPCalendar"
Enable the plugin

See the INSTALLATION wiki page for detailed instructions.

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

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

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

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

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

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

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

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)

# 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, including:

Page	Description
Home	Overview and quick reference
INSTALLATION	Installation guide for Joomla 5.x/6.x
API-Reference	Complete endpoint documentation

License

This project is licensed under the GNU General Public License v3.0 or later -- see the LICENSE file.

Moko Consulting -- MokoStandards