API Category

Read the categories and the category groups of a site, e.g. for the navigation or the filters of a front-end. Part of the Webservice module since v10.0.0, before it was a separate package

WARNING

Since v10.0.0 the Category API is part of the module and read only: managing categories stays in the control panel of ExpressionEngine. The separate Webservice Category API and Webservice Category Group API packages are no longer needed and no longer work, remove reinos_webservice_category_api / webservice_category_api and reinos_webservice_category_group_api / webservice_category_group_api from system/user/addons after updating (Breaking change).

Endpoints

Method	URL	Endpoint
GET	/webservice/category	read_category
GET	/webservice/category/group	read_category_group

Enable the API for a member on the member page, or make an endpoint public to read the categories without credentials. Both endpoints work without data and read the site of data[site_id] (default 1). The responses can be cached.

read_category

Name	Description
cat_id	One or more category ids, an array or comma separated	Optional
group_id	One or more category group ids	Optional
parent_id	The parent category, 0 for the top level	Optional
cat_url_title	The url title	Optional
tree	y to nest the categories: every category has its children. A category whose parent is not in the result is on the top level. No paging	Optional
orderby	cat_id, cat_name, cat_url_title, cat_order, group_id or parent_id. Default: the order of the group (alphabetical or custom) when one group is read, otherwise cat_order	Optional
sort	asc (default) or desc	Optional
limit, offset	Paging, default 25, maximum 100	Optional

curl -G 'https://your-domain.com/index.php/webservice/category' \
  -H 'Authorization: Bearer <shortkey>' \
  --data-urlencode 'data[group_id]=2' \
  --data-urlencode 'data[tree]=y'

{
  "success": true,
  "message": "Successfully read",
  "metadata": {"total_results": 1},
  "data": [
    {
      "cat_id": 4, "site_id": 1, "group_id": 2, "parent_id": 0,
      "cat_name": "Tractors", "cat_url_title": "tractors", "cat_description": "",
      "cat_image": "{file:12:url}", "cat_image_url": "https://your-domain.com/images/tractors.jpg",
      "cat_order": 1, "code": "T1",
      "children": [
        {"cat_id": 10, "parent_id": 4, "cat_name": "Small tractors", "children": []}
      ]
    }
  ]
}

Every category has the custom category fields of its group by short name (code above), cat_image is the value as it is stored, cat_image_url the url of the image.

read_category_group

Name	Description
group_id	One or more group ids, an array or comma separated	Optional
orderby	group_id (default) or group_name	Optional
sort, limit, offset	Sorting and paging	Optional

Every group has group_id, site_id, group_name, sort_order (alphabetical or custom), total_categories, the custom category fields (field_id, field_name, field_label, field_type, field_required) and the channel_ids of the channels that use the group.

Hooks

webservice_read_category_end

The return value replaces the categories of the response.

$categories = ee()->extensions->call('webservice_read_category_end', $categories);

webservice_read_category_group_end

The return value replaces the groups of the response.

$groups = ee()->extensions->call('webservice_read_category_group_end', $groups);

Changes in v10.0.0

• Part of the module and read only, create_category, update_category and delete_category (and the same for groups) no longer exist.
• The groups are read with read_category_group of this API, the separate Category Group API is discontinued.
• The custom fields are returned by short name, the url of the image as cat_image_url, nested categories with tree.