Category API Endpoint
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.
{
"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.
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):
[{
"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.
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):
[{
"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.
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):
[{
"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.
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):
[]