KB User's Guide - API - Categories

This document provides information on the Categories API for the KnowledgeBase.

Title

Get Categories

Calls externally-published categories (aka topics) for the specified site domain.

Collection Endpoint

[KB site domain]/api/v1/categories

Method

GET

URL Params

parameter type description
query text string one or more search terms, separated by a plus sign (plus sign)

Collection Sample Response

{
  "_links": {
    "self": {
      "href": "https://kb.wisc.edu/helpdesk/api/v1/categories?page=1"
    },
    "first": {
      "href": "https://kb.wisc.edu/helpdesk/api/v1/categories"
    },
    "last": {
      "href": "https://kb.wisc.edu/helpdesk/api/v1/categories?page=5"
    },
    "next": {
      "href": "https://kb.wisc.edu/helpdesk/api/v1/categories?page=2"
    }
  },
  "_embedded": {
    "category": [
      {
        "id": "2",
        "cat_id": "1001",
        "parent_id": "931",
        "level": "3",
        "cat_name": "My UW-Madison",
        "cat_desc": "UW Application - My UW-Madison",
        "select_name": "My UW-Madison",
        "int": "1",
        "ext": "1",
        "reminder": "1",
        "hot": "1",
        "admin_only": "0",
        "public_share": "1",
        "parent": "0",
        "group_id": "1",
        "user_group_id": "0",
        "contact_email": "",
        "notify_email": "",
        "doc_id": "0",
        "sort": "0",
        "active": "1",
        "_links": {
          "self": {
            "href": "https://kb.wisc.edu/helpdesk/api/v1/categories/2"
          }
        }
      },
      {
        "id": "5",
        "cat_id": "1004",
        "parent_id": "1656",
        "level": "3",
        "cat_name": "WiscVPN",
        "cat_desc": "UW Application - WiscVPN",
        "select_name": "WiscVPN",
        "int": "1",
        "ext": "1",
        "reminder": "1",
        "hot": "1",
        "admin_only": "0",
        "public_share": "1",
        "parent": "0",
        "group_id": "1",
        "user_group_id": "0",
        "contact_email": "",
        "notify_email": "",
        "doc_id": "0",
        "sort": "0",
        "active": "1",
        "_links": {
          "self": {
            "href": "https://kb.wisc.edu/helpdesk/api/v1/categories/5"
          }
        }
      },

      ...

      }
    ]
  },
  "page_count": 5,
  "page_size": 25,
  "total_items": 112,
  "page": 1
}

Entity Endpoint

/api/v1/categories/[category_id]

Example: /api/v1/categories/2134

Entity Sample Response

{
  "id": "44",
  "parent_id": "3260",
  "level": "2",
  "cat_name": "Mac OS X",
  "cat_desc": "",
  "select_name": "Mac OS X",
  "int": "1",
  "ext": "1",
  "hot": "1",
  "active": "1",
  "_links": {
    "self": {
      "href": "https://kb.wisc.edu/helpdesk/api/v1/categories/44"
    }
  }
}

Success Response

Code: 200 OK
Content: Content-type: application/hal+json

Error Response

Code: 403 Forbidden
Content: {"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html","title":"Forbidden","status":403,"detail":"Forbidden"}

OR

Code: 404 Page Not Found
Content: Page not found.

OR

Code: 405 Method Not Allowed
Content: None

OR

Code: 500 Unexpected error
Content: { error : "Error producing an iterator" }

Notes

N/A