Category API Endpoint

0

Categories are used to organize articles into logical groupings. Before any article can be created, a category must exist as its parent.

Categories themselves are organized in a parent / child tree structure, where initial categories are created without any parent, so are called "root" categories (with a parent_id set to 0, indicating it has no parent).

Using the Category API, you can programmatically access category objects to organize these from your own applications and scripts. Possible uses include creating content, importing data from external sources, or exporting content for backup or any other purpose.


The category object


Attributes

category_id

This is the unique numeric reference for the category. This is used to identity categories in a number of API calls

parent_id

The parent_id identifies the parent category for any other category. If the category is a 'root' category, not having any parent, then it will have a parent_id of 0.

category_name

A descriptive title that is associated with the category and will be displayed when users view articles contained within it. You should limit the length of this to be as short as practical.

Using category names that are too long may cause them to become truncated or displayed incorrectly on certain devices (think of mobile displays, which have less usable area)

slug

The slug is an important value, since it is also a unique reference to the category. This must contain no spaces or special characters. Only alphanumeric characters and hyphens, since it may be used in article URLs

published

A boolean value of true or false indicating whether the category is published or not. Categories that are not published cannot be seen by readers. Only editors and other staff will be able to view them and their contents.

modified_date

A Unix timestamp representing the last time the category was modified

icon_url

This is a URL to the image associated with category. A number of builtin icon_url images have been defined for use by the application and can be selected manually within the web application dashboard when editing a category, however when using this API, you may choose one of the builtin URLs or you can provide your own, as long as the URL references a valid image and it is hosted in a location reachable using HTTPS.

This allows you to specify your own custom images associated with categories if you wish (you are not restricted to referencing builtin GoGoWorx images for this).

See the Categories article for a reference to the builtin category images.

The default value for icon_url if none is specified will be the default icon located at: "https://assets.gogoworx.com/images/category_icons/default-150.png"

Whichever image is specified, it will be resized to fit the target element as needed. Typical sizes used by these images is 72 x 72 pixels, so your image selection should be based on this target resolution.

 Language: json
{
    "category_id": 123,
    "parent_id": 0,
    "category_name": "My Category",
    "slug": "my-category",
    "published": true,
    "modified_date": 1588698334,
    "icon_url": "https://assets.gogoworx.com/images/category_icons/default-150.png"
}



⯁


Retrieve a categoryGET /category

Returns one or more categories matching the specified criteria

Required parameters

At least one of the optional parent_id, category_id or slug parameters must be specified


Optional parameters

parent_id

Unique numeric identifier for the parent category of other categories. If a category is a 'root' category (not having any parent), then it will have a parent_id of 0.

Specifying a parent_id without specifying category_id or slug will return all categories having a parent_id matching the specified value

category_id

Unique numeric identifier for the category.

slug

Unique alphanumeric string reference to the category. This must contain no spaces or special characters. Only alphanumeric characters and hyphens are permitted

limit

Optional limit on the number of category objects to be returned, between 1 and 100

If this parameter is not provided, a default limit of 100 will be applied, returning the maximum of 100 items.

fetch_offset

A cursor to use for pagination. Defines the numeric offset from where results should begin being fetched.

For example, if you were working with a large number of records, and wanted to fetch them in pages of 10 at a time, you might set the limit value to 10 (indicating only 10 records at a time should be returned) and for the first page, fetch_offset would be 0 to indicate no offset (returning records 1-10). For the second page, fetch_offset would be set to 10, allowing records 11-20 to be returned.

If this parameter is not provided, a default fetch_offset of 0 will be applied, returning records from the start of the result set.

 Language: bash [ Line Numbers Enabled ]
curl -X GET https://api.gogoworx.com/category \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"parent_id": 0, "limit": 5}'

Response (containing specified categories):

 Language: json
[{
    "category_id": 123,
    "parent_id": 0,
    "category_name": "My Category",
    "slug": "my-category",
    "published": true,
    "modified_date": 1588698334,
    "icon_url": "https://assets.gogoworx.com/images/category_icons/default-150.png"
},
{
    "category_id": 124,
    "parent_id": 0,
    "category_name": "My Second Category",
    "slug": "my-second-category",
    "published": true,
    "modified_date": 1588698334,
    "icon_url": "https://assets.gogoworx.com/images/category_icons/default-150.png"
},
{
    "category_id": 125,
    "parent_id": 0,
    "category_name": "My Third Category",
    "slug": "my-third-category",
    "published": true,
    "modified_date": 1588698334,
    "icon_url": "https://assets.gogoworx.com/images/category_icons/default-150.png"
}]



⯁


Create a categoryPOST /category

Creates a new category based on the specified criteria.

Note that the weight attribute for newly created categories will be automatically calculated to place the category at the bottom of the list of siblings (the highest numeric weight value). This can be changed after creation by making a PUT request as described below

Required parameters

parent_id

Unique numeric identifier for the parent category of the category being created. If a category is a 'root' category (not having any parent), then it will have a parent_id of 0.

category_name

A descriptive title that is associated with the category and will be displayed when users view articles contained within it. You should limit the length of this to be as short as practical.

Using category names that are too long may cause them to become truncated or displayed incorrectly on certain devices (think of mobile displays, which have less usable area)

There is a maximum length of 55 characters permitted for category_name

slug

Unique alphanumeric string reference to the category. This must contain no spaces or special characters. Only alphanumeric characters and hyphens are permitted


Optional parameters

published

A boolean value of true or false indicating whether the category is published or not. Categories that are not published cannot be seen by readers. Only editors and other staff will be able to view them and their contents.

icon_url

A valid HTTPS hosted image URL. This may be one of the builtin URLs provided by GoGoWorx, or it can be a reference to your own image that you wish to associate with the category, when it is being displayed.

A default value of "https://assets.gogoworx.com/images/category_icons/default-150.png" will be used if this parameter is not specified.

 Language: bash [ Line Numbers Enabled ]
curl -X POST https://api.gogoworx.com/category \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"parent_id": 0, "category_name": "New Category", "slug": "new-category"}'

Response (containing newly created category object):

 Language: json
[{
    "category_id": 126,
    "parent_id": 0,
    "category_name": "New Category",
    "slug": "new-category",
    "published": false,
    "modified_date": 1588698334,
    "icon_url": "https://assets.gogoworx.com/images/category_icons/default-150.png"
}]



⯁


Update a categoryPUT /category

Updates a single, specified category based on the parameters provided

Required parameters

Either category_id or slug must be specified to uniquely identify the category to be updated.


Optional parameters

parent_id

The parent_id identifies the parent category for any other category. If the category is a 'root' category, not having any parent, then it will have a parent_id of 0.

Note that parent_id must reference with a valid category or 0 to classify the category as a 'root' category

category_id

Unique numeric identifier for the category.

category_name

A descriptive title that is associated with the category and will be displayed when users view articles contained within it. You should limit the length of this to be as short as practical.

Using category names that are too long may cause them to become truncated or displayed incorrectly on certain devices. Think of mobile displays, for instance, which have less usable area

slug

Unique alphanumeric string reference to the category. This must contain no spaces or special characters. Only alphanumeric characters and hyphens are permitted

Ideally, you should try to avoid changing the slug parameter whenever possible, since this will change any external URLs that reference the category.

Any internal references within GoGoWorx will automatically update whenever this value is changed (internal references use the immutable category_id value)

Note that in order to change the slug value, you must specify the category_id parameter

weight

The relative weighting value assigned to the category. This value affects where it appears in lists with siblings. Lower values appear towards the top

published

A boolean value of true or false indicating whether the category is published or not. Categories that are not published cannot be seen by readers. Only editors and other staff will be able to view them and their contents.

icon_url

A valid HTTPS hosted image URL. This may be one of the builtin URLs provided by GoGoWorx, or it can be a reference to your own image that you wish to associate with the category, when it is being displayed.

 Language: bash [ Line Numbers Enabled ]
curl -X PUT https://api.gogoworx.com/category \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"category_id": 126, "category_name": "Modified Category Name", \
        "icon_url": "https://assets.gogoworx.com/images/category_icons/home-150.png"}'

Response (containing newly updated category object):

 Language: json
[{
    "category_id": 126,
    "parent_id": 0,
    "category_name": "Modified Category Name",
    "slug": "new-category",
    "published": false,
    "modified_date": 1588698334,
    "icon_url": "https://assets.gogoworx.com/images/category_icons/home-150.png"
}]



⯁


Delete a categoryDELETE /category

Deletes a single, specified category based on the parameters provided.

Note that once deleted, a category can no longer be accessed. If you simply want to remove the category from being visible to readers, update the published flag or modify category_group settings for the category.

Required parameters

Either of category_id or slug must be specified to uniquely identify the category to be deleted.


Optional parameters

category_id

Unique numeric identifier for the category.

slug

Unique alphanumeric string identifier to the category.

 Language: bash [ Line Numbers Enabled ]
curl -X DELETE https://api.gogoworx.com/category \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"category_id": 126}'

Response (containing empty array):

 Language: json
[]