Introduction

The webservices plugin from DPCases extends the official Joomla API endpoint of your web site with the cases. This functionality is offered for developers who want to manage cases in other websites or mobile applications.

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

Make sure the Webservices - DPCases 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

DPCases 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 cases, use then "/api/index.php/v1/dpcases/cases".

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

curl -X GET https://{host}/api/index.php/v1/dpcases/cases?filter[category]=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 case", "catid": 10, "state": 1, "description": "Sample description" }' is needed.

Cases

GET /dpcases/cases

Get a list of cases. 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[category]=12 // The category id

The response is a JSON string like:

{
    "links": {
        "self": "https://{host}/api/index.php/v1/dpcases/cases?XDEBUG_SESSION_START=PHPSTORM"
    },
    "data": [
        {
            "type": "cases",
            "id": "1",
            "attributes": {
                "id": 1,
                "title": "Demo case",
                "alias": "demo-case",
                "description": "<p>This is a demo case <em>description</em>, with some <strong>HTML</strong> tags.</p>",
                "catid": 9,
                "state": 2,
                "access": 1,
                "created": "2024-08-22 13:02:21",
                "created_by": 42,
                "created_by_alias": "",
                "modified": "2024-08-22 13:02:21",
                "modified_by": 42,
                "featured": 0,
                "language": "*",
                "hits": 0,
                "publish_up": null,
                "publish_down": null
            },
            "relationships": {
                "created_by": {
                    "data": {
                        "type": "users",
                        "id": "42"
                    }
                },
                "modified_by": {
                    "data": {
                        "type": "users",
                        "id": "42"
                    }
                }
            }
        }
    ],
    "meta": {
        "total-pages": 1
    }
}

GET /dpcases/cases/:id

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

{
    "links": {
        "self": "https://{host}/api/index.php/v1/dpcases/cases/60"
    },
    "data": {
        "type": "cases",
        "id": "60",
        "attributes": {
            "typeAlias": "com_dpcases.case",
            "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_dpcases/images/hike.jpg",
                "image_intro_alt": "Hike",
                "image_intro_caption": "",
                "image_full": "media/plg_sampledata_dpcases/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": "",
            "catid": "19"
        },
        "relationships": {
            "category": {
                "data": {
                    "type": "categories",
                    "id": "19"
                }
            },
            "created_by": {
                "data": {
                    "type": "users",
                    "id": "42"
                }
            },
            "modified_by": {
                "data": null
            }
        }
    }
}

POST /dpcases/cases

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

{
    "title": "Demo case", 
    "catid": 10, 
    "state": 2,
    "description": "This is a demo case description.",
    "my-custom-field": "ws test"
}

PATCH /dpcases/cases/:id

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

DELETE /dpcases/cases/:id

Deletes an case by id.

Categories

GET /dpcases/categories

Get a list of categories.

GET /dpcases/categories/:id

Get a single category by id.

POST /dpcases/categories

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

{
    "title": "Demo category",
    "published": 1,
    "params": {"color": "#dddddd"}
}

PATCH /dpcases/categories/:id

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

DELETE /dpcases/categories/:id

Deletes an category by id.