Menu

#8753 Webservices plugin

Parent Category:
DPCalendar
Category:
Joomla plugins
Last Updated:
Allon Moritz, Monday, 18 December 2023 08:54
Created:
Friday, 03 September 2021 16:24
Hits:
2291

This feature is part of the DPCalendar Standard subscription.
SubscribePHP 7.4PHP 8Joomla 3.10Joomla 4.4Joomla 5

Introduction

The webservices plugin from DPCalendar extends the official Joomla API endpoint of your web site with calendar data. This functionality is offered for developers who want to integrate event data in other websites or mobile applications.

The integrator has the possibility to read/write/update/delete events, calendars and locations. All returned data can be parsed as JSON, which is nowadays pretty much a standard for REST API's.

Make sure the Webservices - DPCalendar plugin is enabled. More information about the core API endpoints and how to access them can be found here. How to enable authentication can be found here.

Endpoints

DPCalendar offers the following endpoints as HTTP requests. The first word is the HTTP method to use. Parameters are starting with a double point. All endpoints are available under the following path "/api/index.php/v1". To get all events, use then "/api/index.php/v1/dpcalendar/events".

To test these endpoints you can run in a terminal the following command:

curl -X GET https://{host}/api/index.php/v1/dpcalendar/events?filter[calids]=12 -H "Authorization: Bearer {token}"

  • Replace GET with another method as described below, can either be POST, PUT or DELETE.
  • {host} should point to your Joomla installation and {token} is your Joomla API token. This token can be obtained while editing your user profile, keep in mind that it only works for super admin users.
  • The filter[xxx] argument does define filtering options for the request to narrow the search result.
  • If a POST or PUT request is done, then an additional option is required to send the data in the request body as JSON string, the parameter -d '{ "title": "Demo event", "calid": 10, "start_date": "2023-09-15 10:00:00", "end_date": "2023-09-15 11:00:00" }' is needed.

Events

GET /dpcalendar/events

Get a list of events. The following query options are available with an example value:

  • page[limit]=3 // How many item should be returned
  • page[offset]=2 // The start page of items
  • filter[start_date]=2023-08-14T16:30:00Z // The start date as ISO 8601 format
  • filter[end_date]=2023-09-19T09:45:00Z // The start date as ISO 8601 format
  • filter[calids]=12 // The calendar ID's, can be a comma separated string
  • filter[search]=Demo event // A search string, ensure it is urlencoded
  • filter[expand]=1 // Should only the original event be returned or every instance of a series

The response is a JSON string like:

{
    "links": {
        "self": "http://{host}/api/index.php/v1/dpcalendar/events?page[limit]=3",
        "next": "http://{host}/api/index.php/v1/dpcalendar/events?page[limit]=3&page[offset]=3",
        "last": "http://{host}/api/index.php/v1/dpcalendar/events?page[limit]=3&page[offset]=18"
    },
    "data": [
        {
            "type": "events",
            "id": "60",
            "attributes": {
                "id": 60,
                "title": "Mountain hike",
                "alias": "mountain-hike-1703149200",
                "rrule": null,
                "exdates": null,
                "start_date": "2023-12-21 09:00:00",
                "end_date": "2023-12-21 11:00:00",
                "images": {
                    "image_intro": "media/plg_sampledata_dpcalendar/images/hike.jpg",
                    "image_intro_width": 800,
                    "image_intro_height": 457,
                    "image_intro_alt": "Hike",
                    "image_intro_caption": "",
                    "image_intro_dimensions": "width=\"800\" height=\"457\"",
                    "image_full": "media/plg_sampledata_dpcalendar/images/hike.jpg",
                    "image_full_width": 800,
                    "image_full_height": 457,
                    "image_full_alt": "Hike",
                    "image_full_caption": "",
                    "image_full_dimensions": "width=\"800\" height=\"457\""
                },
                "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>",
                "hits": 0,
                "capacity": null,
                "state": 1,
                "access": 1,
                "language": "*",
                "created": "2023-12-18 08:21:25",
                "created_by": 42,
                "created_by_alias": "",
                "modified": null,
                "modified_by": 0,
                "metakey": null,
                "metadesc": null,
                "metadata": null,
                "featured": 0,
                "publish_up": null,
                "publish_down": null,
                "tags": [],
                "calid": "19"
            },
            "relationships": {
                "calendar": {
                    "data": {
                        "type": "calendars",
                        "id": "19"
                    }
                },
                "created_by": {
                    "data": {
                        "type": "users",
                        "id": "42"
                    }
                }
            }
        },
        {
            "type": "events",
            "id": "71",
            "attributes": {
                "id": 71,
                "title": "Lake swimming",
                "alias": "lake-swimming-1703322000",
                "rrule": null,
                "exdates": null,
                "start_date": "2023-12-23 09:00:00",
                "end_date": "2023-12-23 11:00:00",
                "images": {
                    "image_intro": "media/plg_sampledata_dpcalendar/images/swimming.jpg",
                    "image_intro_width": 800,
                    "image_intro_height": 535,
                    "image_intro_alt": "Swimming",
                    "image_intro_caption": "",
                    "image_intro_dimensions": "width=\"800\" height=\"535\"",
                    "image_full": "media/plg_sampledata_dpcalendar/images/swimming.jpg",
                    "image_full_width": 800,
                    "image_full_height": 535,
                    "image_full_alt": "Swimming",
                    "image_full_caption": "",
                    "image_full_dimensions": "width=\"800\" height=\"535\""
                },
                "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>",
                "hits": 0,
                "capacity": null,
                "state": 1,
                "access": 1,
                "language": "*",
                "created": "2023-12-18 08:21:25",
                "created_by": 42,
                "created_by_alias": "",
                "modified": null,
                "modified_by": 0,
                "metakey": null,
                "metadesc": null,
                "metadata": null,
                "featured": 0,
                "publish_up": null,
                "publish_down": null,
                "tags": [],
                "calid": "19"
            },
            "relationships": {
                "calendar": {
                    "data": {
                        "type": "calendars",
                        "id": "19"
                    }
                },
                "created_by": {
                    "data": {
                        "type": "users",
                        "id": "42"
                    }
                }
            }
        },
        {
            "type": "events",
            "id": "92",
            "attributes": {
                "id": 92,
                "title": "Rock concert",
                "alias": "rock-concert-1703322000",
                "rrule": null,
                "exdates": null,
                "start_date": "2023-12-23 09:00:00",
                "end_date": "2023-12-23 11:00:00",
                "images": {
                    "image_intro": "media/plg_sampledata_dpcalendar/images/rock-concert.jpg",
                    "image_intro_width": 800,
                    "image_intro_height": 533,
                    "image_intro_alt": "Rock concert",
                    "image_intro_caption": "",
                    "image_intro_dimensions": "width=\"800\" height=\"533\"",
                    "image_full": "media/plg_sampledata_dpcalendar/images/rock-concert.jpg",
                    "image_full_width": 800,
                    "image_full_height": 533,
                    "image_full_alt": "Rock concert",
                    "image_full_caption": "",
                    "image_full_dimensions": "width=\"800\" height=\"533\""
                },
                "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>",
                "hits": 0,
                "capacity": 80,
                "state": 3,
                "access": 1,
                "language": "*",
                "created": "2023-12-18 08:21:26",
                "created_by": 42,
                "created_by_alias": "",
                "modified": null,
                "modified_by": 0,
                "metakey": null,
                "metadesc": null,
                "metadata": null,
                "featured": 0,
                "publish_up": null,
                "publish_down": null,
                "tags": [],
                "calid": "19"
            },
            "relationships": {
                "calendar": {
                    "data": {
                        "type": "calendars",
                        "id": "19"
                    }
                },
                "created_by": {
                    "data": {
                        "type": "users",
                        "id": "42"
                    }
                }
            }
        }
    ],
    "meta": {
        "total-pages": 7
    }
}
GET /dpcalendar/events/:id

Get a single event by id. The response is a JSON string like:

{
    "links": {
        "self": "http://joomla.box/j5/api/index.php/v1/dpcalendar/events/60"
    },
    "data": {
        "type": "events",
        "id": "60",
        "attributes": {
            "typeAlias": "com_dpcalendar.event",
            "id": 60,
            "title": "Mountain hike",
            "alias": "mountain-hike-1703149200",
            "rrule": null,
            "exdates": null,
            "start_date": "2023-12-21 09:00:00",
            "end_date": "2023-12-21 11:00:00",
            "images": {
                "image_intro": "media/plg_sampledata_dpcalendar/images/hike.jpg",
                "image_intro_alt": "Hike",
                "image_intro_caption": "",
                "image_full": "media/plg_sampledata_dpcalendar/images/hike.jpg",
                "image_full_alt": "Hike",
                "image_full_caption": "",
                "image_intro_width": 800,
                "image_intro_height": 457,
                "image_full_width": 800,
                "image_full_height": 457
            },
            "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>",
            "hits": 0,
            "capacity": null,
            "state": 1,
            "access": 1,
            "language": "*",
            "created": "2023-12-18 08:21:25",
            "created_by": 42,
            "created_by_alias": "",
            "modified": null,
            "modified_by": 0,
            "metakey": null,
            "metadesc": null,
            "metadata": [],
            "featured": 0,
            "publish_up": null,
            "publish_down": null,
            "tags": [],
            "field-en-gb-1": "",
            "field-en-gb-2": "",
            "field-en-gb-3": "",
            "calid": "19"
        },
        "relationships": {
            "calendar": {
                "data": {
                    "type": "calendars",
                    "id": "19"
                }
            },
            "created_by": {
                "data": {
                    "type": "users",
                    "id": "42"
                }
            },
            "modified_by": {
                "data": null
            }
        }
    }
}
POST /dpcalendar/events

Create a new event, the body is the data of the new event. The request body must be a JSON encoded array where the indexes reflect the attributes of the event. Custom fields should be added by their name field. The following example is a JSON string which creates an event with the required fields, a custom field, a location and host:

{
    "title": "Demo event", 
    "calid": 10, 
    "start_date": "2023-09-15 10:00:00",
    "end_date": "2023-09-15 11:00:00",
    "my-custom-field": "ws test",
    "location_ids": [9, 12],
    "host_ids": [43, 44]
}
PATCH /dpcalendar/events/:id

Update an existing event by id, the body is the data of the updated event similar to the create command.

DELETE /dpcalendar/events/:id

Deletes an event by id.

Calendars

GET /dpcalendar/calendars

Get a list of calendars.

GET /dpcalendar/calendars/:id

Get a single calendar by id.

POST /dpcalendar/calendars

Create a new calendar, the body is the data of the new calendar. The request body must be a JSON encoded array where the indexes reflect the attributes of the calendar. Custom fields are currently not supported. The following example is a JSON string which creates a calendar with the required fields:

{
    "title": "Demo calendar",
    "published": 1,
    "params": {"color": "#dddddd"}
}
PATCH /dpcalendar/calendars/:id

Update an existing calendar by id, the body is the data of the updated calendar similar to the create command.

DELETE /dpcalendar/calendars/:id

Deletes an calendar by id.

Locations

GET /dpcalendar/locations

Get a list of locations. The following query options are available with an example value:

  • page[limit]=3 // How many item should be returned
  • page[offset]=2 // The start page of items
  • filter[search]=Demo event // Search term in title and alias

The response is a JSON string like:

{
    "links": {
        "self": "http://{host}/api/index.php/v1/dpcalendar/locations?page[limit]=3",
        "next": "http://{host}/api/index.php/v1/dpcalendar/locations?page[limit]=3&page[offset]=3",
        "last": "http://{host}/api/index.php/v1/dpcalendar/locations?page[limit]=3&page[offset]=18"
    },
    "data": [
        {
            "type": "locations",
            "id": "1",
            "attributes": {
                "id": 1,
                "title": "Los  Angeles",
                "alias": "los-angeles",
                "country": 242,
                "province": "California",
                "city": "Los Angeles",
                "zip": "90012",
                "street": "North Alameda Street",
                "number": "301-399",
                "rooms": [],
                "latitude": "34.05084950",
                "longitude": "-118.23809670",
                "url": "",
                "description": null,
                "color": "2e3877",
                "state": 1,
                "language": "*",
                "created": "2023-12-09 16:07:49",
                "created_by": 42,
                "created_by_alias": "",
                "modified": null,
                "modified_by": 0,
                "publish_up": null,
                "publish_down": null,
                "metadata": null
            }
        },
        {
            "type": "locations",
            "id": "2",
            "attributes": {
                "id": 2,
                "title": "New York",
                "alias": "new-york",
                "country": 242,
                "province": "New York",
                "city": "New York",
                "zip": "10007",
                "street": "Broadway",
                "number": "230",
                "rooms": [],
                "latitude": "40.71276550",
                "longitude": "-74.00599370",
                "url": "",
                "description": null,
                "color": "7345ba",
                "state": 1,
                "language": "*",
                "created": "2023-12-09 16:07:49",
                "created_by": 42,
                "created_by_alias": "",
                "modified": null,
                "modified_by": 0,
                "publish_up": null,
                "publish_down": null,
                "metadata": null
            }
        },
        {
            "type": "locations",
            "id": "3",
            "attributes": {
                "id": 3,
                "title": "Washington",
                "alias": "washington",
                "country": 242,
                "province": "District of Columbia",
                "city": "Washington",
                "zip": "20502",
                "street": "Ellipse Road Northwest",
                "number": "",
                "rooms": [],
                "latitude": "38.89519300",
                "longitude": "-77.03662770",
                "url": "",
                "description": null,
                "color": "914a6e",
                "state": 1,
                "language": "*",
                "created": "2023-12-09 16:07:49",
                "created_by": 42,
                "created_by_alias": "",
                "modified": null,
                "modified_by": 0,
                "publish_up": null,
                "publish_down": null,
                "metadata": null
            }
        }
    ],
    "meta": {
        "total-pages": 7
    }
}
GET /dpcalendar/locations/:id

Get a single location by id. The response is a JSON string like:

{
    "links": {
        "self": "https://{host}/api/index.php/v1/dpcalendar/locations/2"
    },
    "data": {
        "type": "locations",
        "id": "2",
        "attributes": {
            "typeAlias": "com_dpcalendar.location",
            "id": 2,
            "title": "New York",
            "alias": "new-york",
            "country": 242,
            "province": "New York",
            "city": "New York",
            "zip": "10007",
            "street": "Broadway",
            "number": "230",
            "rooms": [],
            "latitude": "40.71276550",
            "longitude": "-74.00599370",
            "url": "",
            "description": null,
            "color": "7345ba",
            "state": 1,
            "language": "*",
            "created": "2023-12-09 16:07:49",
            "created_by": 42,
            "created_by_alias": "",
            "modified": null,
            "modified_by": 0,
            "publish_up": null,
            "publish_down": null,
            "metadata": {},
            "demo-field": ""
        },
        "relationships": {
            "modified_by": {
                "data": null
            }
        }
    }
}
POST /dpcalendar/locations

Create a new location, the body is the data of the new location. The request body must be a JSON encoded array where the indexes reflect the attributes of the location. Custom fields should be added by their name field. If no "latitude" and "longitude" attributes are defined, then they will be fetched by a geolocation lookup automatically. The following example is a JSON string which creates a location with the required fields and a custom field:

{
    "title": "Demo location", 
    "country": "US", 
    "city": "New York",
    "demo-field": "ws test"
}

The country field can either be the two letter ISO code or the ID from the database.

PATCH /dpcalendar/locations/:id

Update an existing location by id, the body is the data of the updated location similar to the create command.

DELETE /dpcalendar/locations/:id

Deletes an location by id.

Comments (0)

We use cookies on our website. Some of them are essential for the operation of the site, while others help us to improve this site and the user experience (tracking cookies). You can decide for yourself whether you want to allow cookies or not. Please note that if you reject them, you may not be able to use all the functionalities of the site.