Managing Categories
This series of API calls allows you to create, delete and fetch all categories within a Rev account. You can also specify that a category is restricted and assign the category roles that have the ability to assign content to it.
Create
Create a new category. If you specify it as a restricted category, you can assign the users and groups who may assign content to it and what type of access they have.
POST
/api/v2/categories
Request Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | category name | Yes |
| parentCategoryId | string | GUID for the parent category when creating child categories. | |
| restricted | boolean | When true, the category is restricted and only the users and groups specified may add or edit content in the category or the category itself. | |
| categoryPolicyItems | array ([categoryPolicyItem]) | Used to add the users and groups that may add or edit content or a category when it is designated restricted. | |
| id | string, categoryPolicyItem | Id of the access control entity to give access to. | |
| type | string, categoryPolicyItem | Type of entity. Can be a user or group. | |
| itemType | string, categoryPolicyItem | Role to assign. Can be a CategoryContributor or CategoryManager. Only managers can edit the categories themselves. View Rev help for more details. |
Example Request
{
"name": "Secure category 001",
"restricted": true,
"categoryPolicyItems": [
{ "type": "User", "id": "5d8ebc19-fad7-40fc-9682-bbd6a56a89b4", "itemType": "CategoryManager"}
,
{"type": "Group", "id": "ace9c31c-aae7-43c7-8ce3-0f85f192b159", "itemType": "CategoryContributor"}
],
"parentCategoryId": "b785b004-e678-404a-97db-8cb3dcf658c9"
}
Example Response
{
"categoryId": "3990c5d4-088a-4e36-9024-a0473cc6bb89",
"name": "Secure category 002",
"parentCategory":
{"categoryId": "b785b004-e678-404a-97db-8cb3dcf658c9", "name": "Secure Parent", "parentCategory": null}
}
Response Codes
| Code | Description |
|---|---|
| 200 | ok |
| 401 | Unauthorized error |
| 500 | Internal server error |
Edit
Edit a category. If it is a restricted category, you can also edit the users and groups who may assign content to it and what type of access they have.
PUT
/api/v2/categories/{categoryId}
Request Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | category name to edit | Yes |
| restricted | boolean | When true, the category is restricted and only the users and groups specified may add or edit content in the category or the category itself. | |
| categoryPolicyItems | array ([categoryPolicyItem]) | Used to add the users and groups that may add or edit content or a category when it is designated restricted. | |
| id | string, categoryPolicyItem | Id of the access control entity to give access to. | |
| type | string, categoryPolicyItem | Type of entity. Can be a user or group. | |
| itemType | string, categoryPolicyItem | Role to assign. Can be a CategoryContributor or CategoryManager. Only managers can edit the categories themselves. View Rev help for more details. |
Example Request
{
"name": "Secure category 001",
"restricted": true,
"categoryPolicyItems": [
{ "type": "User", "id": "5d8ebc19-fad7-40fc-9682-bbd6a56a89b4", "itemType": "CategoryManager"}
,
{"type": "Group", "id": "ace9c31c-aae7-43c7-8ce3-0f85f192b159", "itemType": "CategoryContributor"}
],
"parentCategoryId": "b785b004-e678-404a-97db-8cb3dcf658c9"
}
Response Codes
| Code | Description |
|---|---|
| 200 | ok |
| 401 |
Unauthorized error |
| 500 |
Internal server error
|
Delete
DELETE
/api/v2/categories/{categoryId}
Request Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| categoryId | path | GUID for the category. | Yes |
Response Codes
| Code | Description |
|---|---|
| 200 | ok |
| 401 | Unauthorized error |
| 500 | Internal server error |
Get a Category
Retrieve a specific category.
GET
/api/v2/categories/{categoryId}
Path Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| categoryId | string | Category Id to return | Yes |
Example Response
{
"categoryId": "string",
"name": "string",
"parentCategoryId": "string",
"restricted": true,
"categoryPolicyItems": [
{
"id": "string",
"type": "User",
"itemType": "CategoryContributor"
}
]
}
Response Codes
| Code | Description |
|---|---|
| 200 | ok |
| 401 | Unauthorized error |
| 500 | Internal server error |
List All Categories
GET
/api/v2/categories
Request Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| parentCategoryId | string | All child categories of given parentCategoryId will be returned. If parentCategoryId is not supplied all categories will be returned. | |
| includeAllDescendants | boolean | true/false. If false, then return categories only at one level. If not provided or true, then return all the nested categories. |
Example Response
{
"categories": [
{
"categoryId": "47c36208-42e5-48b8-8def-a0779f3de196",
"name": "Education",
"fullPath": "Education"
},
{
"categoryId": "2d1ea902-fe96-4031-aef0-5af800d95fe4",
"name": "Schools",
"fullPath": "Schools"
},
{
"categoryId": "0b091ac2-398f-4879-a9de-a459c34c1751",
"name": "Sports",
"fullPath": "Schools\Sports"
} ]
}
Response Codes
| Code | Description |
|---|---|
| 200 | ok |
| 401 | Unauthorized error |
| 500 | Internal server error |
- Create
-
Create
Create a new category. If you specify it as a restricted category, you can assign the users and groups who may assign content to it and what type of access they have.
POST/api/v2/categoriesRequest Parameters
Name Type Description Required name string category name Yes parentCategoryId string GUID for the parent category when creating child categories. restricted boolean When true, the category is restricted and only the users and groups specified may add or edit content in the category or the category itself. categoryPolicyItems array ([categoryPolicyItem]) Used to add the users and groups that may add or edit content or a category when it is designated restricted. id string, categoryPolicyItem Id of the access control entity to give access to. type string, categoryPolicyItem Type of entity. Can be a user or group. itemType string, categoryPolicyItem Role to assign. Can be a CategoryContributor or CategoryManager. Only managers can edit the categories themselves. View Rev help for more details. Example Request
{ "name": "Secure category 001", "restricted": true, "categoryPolicyItems": [ { "type": "User", "id": "5d8ebc19-fad7-40fc-9682-bbd6a56a89b4", "itemType": "CategoryManager"} , {"type": "Group", "id": "ace9c31c-aae7-43c7-8ce3-0f85f192b159", "itemType": "CategoryContributor"} ], "parentCategoryId": "b785b004-e678-404a-97db-8cb3dcf658c9" }Example Response
{ "categoryId": "3990c5d4-088a-4e36-9024-a0473cc6bb89", "name": "Secure category 002", "parentCategory": {"categoryId": "b785b004-e678-404a-97db-8cb3dcf658c9", "name": "Secure Parent", "parentCategory": null} }Response Codes
Code Description 200 ok 401 Unauthorized error 500 Internal server error - Edit
-
Edit
Edit a category. If it is a restricted category, you can also edit the users and groups who may assign content to it and what type of access they have.
PUT/api/v2/categories/{categoryId}Request Parameters
Name Type Description Required name string category name to edit Yes restricted boolean When true, the category is restricted and only the users and groups specified may add or edit content in the category or the category itself. categoryPolicyItems array ([categoryPolicyItem]) Used to add the users and groups that may add or edit content or a category when it is designated restricted. id string, categoryPolicyItem Id of the access control entity to give access to. type string, categoryPolicyItem Type of entity. Can be a user or group. itemType string, categoryPolicyItem Role to assign. Can be a CategoryContributor or CategoryManager. Only managers can edit the categories themselves. View Rev help for more details. Example Request
{ "name": "Secure category 001", "restricted": true, "categoryPolicyItems": [ { "type": "User", "id": "5d8ebc19-fad7-40fc-9682-bbd6a56a89b4", "itemType": "CategoryManager"} , {"type": "Group", "id": "ace9c31c-aae7-43c7-8ce3-0f85f192b159", "itemType": "CategoryContributor"} ], "parentCategoryId": "b785b004-e678-404a-97db-8cb3dcf658c9" }Response Codes
Code Description 200 ok 401 Unauthorized error
500 Internal server error
- category name matches another category under the same parent
- category id does not match a valid category
- invalid users and/or groups assigned
- Delete
-
Delete
DELETE/api/v2/categories/{categoryId}Request Parameters
Name Type Description Required categoryId path GUID for the category. Yes Response Codes
Code Description 200 ok 401 Unauthorized error 500 Internal server error - Get
-
Get a Category
Retrieve a specific category.
GET/api/v2/categories/{categoryId}Path Parameters
Name Type Description Required categoryId string Category Id to return Yes Example Response
{ "categoryId": "string", "name": "string", "parentCategoryId": "string", "restricted": true, "categoryPolicyItems": [ { "id": "string", "type": "User", "itemType": "CategoryContributor" } ] }Response Codes
Code Description 200 ok 401 Unauthorized error 500 Internal server error - List
-
List All Categories
GET/api/v2/categoriesRequest Parameters
Name Type Description Required parentCategoryId string All child categories of given parentCategoryId will be returned. If parentCategoryId is not supplied all categories will be returned. includeAllDescendants boolean true/false. If false, then return categories only at one level. If not provided or true, then return all the nested categories. Example Response
{ "categories": [ { "categoryId": "47c36208-42e5-48b8-8def-a0779f3de196", "name": "Education", "fullPath": "Education" }, { "categoryId": "2d1ea902-fe96-4031-aef0-5af800d95fe4", "name": "Schools", "fullPath": "Schools" }, { "categoryId": "0b091ac2-398f-4879-a9de-a459c34c1751", "name": "Sports", "fullPath": "Schools\Sports" } ] }Response Codes
Code Description 200 ok 401 Unauthorized error 500 Internal server error