Handling "Categories"

Intro

The “Categories“ are entities that are used to categorise other entities like: Articles/Videos/Galleries.
The “Categories“ support a nested structure, meaning that each category can have a sub-category.

In this tutorial we will be exploring the Category CRUD operations. To better understand the topic, we will go through the following steps:

Components of a Category
Creating a Category
Updating a Category
Deleting a Category
Get a single category
Get list of categories

Components of a Category

The category consists of the following fields

{
  "id": 0,
  "title": "string",
  "description": "string",
  "main_media": [
    {
      "resource_id": "string",
      "resource_type": "image",
      "resource_subtype": "default",
      "provider": "smp",
      "description": "string",
      "data": {}
    }
  ],
  "active": true,
  "parent_id": "string",
  "weight": 0,
  "subs": [
    "string"
  ],
  "seo": {
    "slug": "string",
    "title": "string",
    "description": "string",
    "keywords": [
      "string"
    ],
    "index": true,
    "follow": true,
    "redirect_type": "temporary"
  },
  "created_at": "string",
  "updated_at": "string",
  "generic": {},
  }

id - Automatically generated by the system.

title - The title of the category.

description - Description for the category.

active - The state of the category: active or inactive. This configuration is used to indicate if the category is active or inactive.

parent_id - The id of the parent category.

weight - Used to indicate the position of the category.

subs - An array containing a list of sub categories (full category objects are returned when requested).

created_at - Date time string, automatically generated by the system when creating a category.

updated_at - Date time string, automatically generated by the system when updating a category.

generic - A generic field which can contain any type of data structure, it is not validated in any way. This field is usually used when a migration is done and data that is not supported by the Content API is needed.

main_media - A field containing data about the asset (Image/Video/Embeded Video) which has been appended to the specified category. The main_media may use one of the following Content entities: Image, Video or an embedded video (not a Content entity).

Creating a Category

To create a category the following request must be made:

End-point: /categories
Request Type: POST
Headers: 
{
  "Authorization": "Bearer <your token>",
  "Project": "<project domain>"
}
Request body:
{
  "title": "string", //mandatory
  "description": "string",
  "active": true,
  "parent_id": "string", //The id of the parent if this category is a child of another category
}

Updating a Category

To update a category the following request must be made:

End-point: /categories/<category id>
Request Type: PATCH
Headers: 
{
  "Authorization": "Bearer <your token>",
  "Project": "<project domain>"
}
Request body:
{
  "title": "string", //mandatory
  "description": "string",
  "active": true,
  "parent_id": "string", //The id of the parent if this category is a child of another category
}

Deleting a Category

To delete a category the following request must be made:

Get a single Category

To get a category the following request must be made:

Get list of Categories

To get a list categories the following request must be made:

The category listing endpoint supports pagination. There are additional parameters that can be used:

Parameters

limit
- Description: Controls how many categories will be returned per page
- Values:
  - Maximum value: 200
  - Default value: 20
- Behaviour: Affects how many pages are generated.
  Example: If there are 60 categories and the limit is set to 10, this will generate 6 pages of categories.
- Request:
page
- Description: Controls which categories page will be retrieved
- Values:
- Behaviours: Affected by the “limit“ parameter
- Request
  - Without “limit“ parameter
  - With “limit“ parameter