Skip to main content

Documentation: Admin Checklist

Web Services API

The Web Services API is only available in the PRO version.
Unlock this and other features by upgrading to Joomill Admin Checklist PRO

Go PRO

Available since version 1.7.0. The Joomill Admin Checklist - Web Services plugin opens the Joomla API for your checklist, so another system can list, create, change, tick off and delete tasks, and manage the categories they live in.

Enable the API

The plugin is part of the PRO package and is switched off after installation, because enabling it opens web addresses on your site. Switch it on only when you want to use the API.

  1. Go to System > Manage > Plugins, search for Joomill Admin Checklist - Web Services and enable it.
  2. Check that the core plugins API Authentication - Web Services Joomla Token and User - Joomla API Token are enabled.
  3. Open the user the other system will work as under Users > Manage, go to the Joomla API Token tab and copy the token.

Out of the box Joomla only accepts tokens of Super Users. For any other user, two Joomla settings have to allow the user's group, otherwise every call answers 401:

  • the Allowed User Groups option of the User - Joomla API Token plugin, and
  • the Web Services Login permission under System > Global Configuration > Permissions.

As long as the plugin is disabled every address below answers 404, exactly like an unknown id. If a call unexpectedly returns 404, check the plugin first.

Making a request

All addresses start with https://www.example.com/api/index.php/v1/checklist/. Send the token in the X-Joomla-Token header and send Accept: application/vnd.api+json, or no Accept header at all. A request with Accept: application/json is refused with 406. Request bodies are plain JSON with Content-Type: application/json.

curl -H "X-Joomla-Token: YOUR_TOKEN" \
     -H "Accept: application/vnd.api+json" \
     https://www.example.com/api/index.php/v1/checklist/tasks

Endpoints and permissions

A valid token is not enough by itself. Every call also needs the matching permission on Admin Checklist for the user behind the token. You set those under Components > Admin Checklist > Options > Permissions.

Method Address What it does Permission
GET tasks List the tasks Access Administration Interface
GET tasks/ID Read one task Access Administration Interface
POST tasks Create a task Create
PATCH tasks/ID Change a task Edit, plus Edit State when you send state
PATCH tasks/ID/check Tick a task off, or untick it Check Tasks
DELETE tasks/ID Delete a trashed task Delete
GET categories List the checklist categories Access Administration Interface
GET categories/ID Read one category Access Administration Interface
POST categories Create a category Create
PATCH categories/ID Change a category Edit
DELETE categories/ID Delete a trashed, empty category Delete

GET and PATCH answer 200 with the task or category, POST answers 201 with the new one, and DELETE answers 204 without a body.

Tasks

A task needs a title and a category, which is the id of a checklist category. Everything else is optional.

curl -X POST \
     -H "X-Joomla-Token: YOUR_TOKEN" \
     -H "Accept: application/vnd.api+json" \
     -H "Content-Type: application/json" \
     -d '{"title":"Check the backups","category":12}' \
     https://www.example.com/api/index.php/v1/checklist/tasks
title, description The task itself. Links to administrator screens in the description are stored in their short form (index.php?option=...), and the answer shows you the stored result.
category The id of the checklist category.
priority 1 is Low, 2 is Normal (the default), 3 is High.
state 1 is published, 0 is unpublished, -2 is trashed.
ordering The position within the category.
duedate, assignedto, recurring Only writable while the Due Date, Assigned To or Recurring Tasks plugin is enabled. Otherwise the whole request is refused with 422 and nothing is saved. Reading them always works.
checked, checked_by, checked_time Whether the task is ticked off, by whom and when. Change them with the check action below.

Tick a task off

Send {"checked": true} to tick a task off as the user behind the token, or {"checked": false} to clear it again. Any other value is refused with 422.

curl -X PATCH \
     -H "X-Joomla-Token: YOUR_TOKEN" \
     -H "Accept: application/vnd.api+json" \
     -H "Content-Type: application/json" \
     -d '{"checked":true}' \
     https://www.example.com/api/index.php/v1/checklist/tasks/42/check

Delete a task

A task has to be in the trash before it can be deleted, so one call can never destroy a task. Send PATCH with {"state": -2} first, then DELETE. Deleting a task that is not trashed answers 409.

Categories

Checklist categories are ordinary Joomla categories of Admin Checklist. The API only ever shows and changes those: the id of a category of another component, such as an article category, answers 404.

A category needs a title. A new category is created unpublished, the same way the Joomla API creates any category, so send "published": 1 along if it should be visible in the checklist right away. You can also send alias, description, note and parent_id.

Deleting works like it does for tasks: trash the category first with {"published": -2}, then delete it. A category that still holds tasks, trashed ones included, is refused with 409.

A token that may only tick tasks off

Because every action has its own permission, you can hand out a token that can tick tasks off and do nothing else:

  1. Create a user group under Users > Groups and put a new user in it.
  2. Under Components > Admin Checklist > Options > Permissions, allow that group Check Tasks and nothing else.
  3. Add the group to Allowed User Groups in the User - Joomla API Token plugin.
  4. Allow the group Web Services Login under System > Global Configuration > Permissions.
  5. Copy the token from the user's Joomla API Token tab.

With that token the check call works and every other call, reading tasks included, answers 403. Without steps 3 and 4 the token is refused with 401.

A user with Check Tasks but without Edit State can tick tasks off in the administrator as well.

Error codes

400 The data was refused, for example a task without a title.
401 The token is missing or not valid, or the user's group is not allowed to use the Joomla API.
403 The token is valid, but its user lacks the permission for this call.
404 The id does not exist, the category belongs to another component, or the Web Services plugin is disabled.
406 The Accept header is not application/vnd.api+json.
409 Deleting a task or category that is not trashed, or a category that still holds tasks.
422 Writing a field whose plugin is disabled, or a check call without true or false.