Using labels on content makes it easy to categorize and search for content relevant to your users. Did you know that you can also create labels and label groups using the API? 

Category Classes? Categories? Labels? Label Groups? What's the difference?

In the Igloo API, labels are called 'Categories', and label groups are referred to as 'Category Classes'.   

Category Classes

Category Classes(label groups) allow you to organize your categories(labels) into meaningful groups. This is especially useful if you have multiple types of categories. For example, if you want to have a group of labels that identify content related to Corporate initiatives, you could create a Category Class called 'Corporate' that contains the Categories "Corporate News", "Corporate Events" and "Corporate Policies". In fact, this group may already be created in your digital workplace. 

Listing category classes using the API

To programmatically view what Category Classes exist within your workplace, you would make a GET request to /.api/api.svc/categories/classes/view.

The response will return something similar to this:

<IglooApiResponse xmlns="http://schemas.iglooplatform.com/Igloo.Old.Common" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <minRequestPeriod>0</minRequestPeriod>
  <requestSupportCode>637049599822357905</requestSupportCode>
  <dictionary i:nil="true" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
  <response i:type="IglooList">
    <startIndex>0</startIndex>
    <count>8</count>
    <totalCount>8</totalCount>
    <items>
      <object i:type="categoryClass">
        <id>55137</id>
        <href/>
        <navType>None</navType>
        <name>Corporate News</name>
      </object>
        .
        .
        .
     </items>
  </response>
</IglooApiResponse>

In the example above, I've stripped out all but the first items to keep things short, but you can see that there are 8 category classes in this workplace, and the first is "Corporate News". The important value here is the id of the Category Class, which in our case it is 55137. We can use this id to view a list of the Categories contained within the Category Class specified by the id.

Listing categories using the API 

To programmatically view what Categories exist within a Category Class, you can make a GET request to /.api/api.svc/categories/classes/{categoryClassId}/viewCategories.

We'll substitute {categoryClassId} with the ID of our Category Class as follows:

GET /.api/api.svc/categories/classes/55137/viewCategories 

The response will return something similar to this:

<IglooApiResponse xmlns="http://schemas.iglooplatform.com/Igloo.Old.Common" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <minRequestPeriod>0</minRequestPeriod>
  <requestSupportCode>637049612929547403</requestSupportCode>
  <dictionary i:nil="true" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
  <response i:type="IglooList">
    <startIndex>0</startIndex>
    <count>14</count>
    <totalCount>14</totalCount>
    <items>
      <object i:type="category">
        <id>382517</id>
        <href/>
        <navType>None</navType>
        <name>Presentation</name>
        <ClassID>55137</ClassID>
      </object>
      <object i:type="category">
        <id>382520</id>
        <href/>
        <navType>None</navType>
        <name>Whitepaper</name>
        <ClassID>55137</ClassID>
      </object>

Again, I've truncated the output for readability, but you can see here that there are 14 Categories in this Category Class, the first two are "Presentation" and "Whitepaper".

Adding category classes using the API

To programmatically add Category Classes, you can make a POST call to /.api/api.svc/categories/classes/add and pass 'name' as a parameter, as shown here: /.api/api.svc/categories/classes/add?name=Developer%20Relations%20News 

Let's add a Category Class called "Developer Relations News", it will return some very important information:

<IglooApiResponse xmlns="http://schemas.iglooplatform.com/Igloo.Old.Common" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <minRequestPeriod>0</minRequestPeriod>
  <requestSupportCode>637049615055499810</requestSupportCode>
  <dictionary i:nil="true" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
  <response i:type="categoryClass">
    <id>100498</id>
    <href/>
    <navType>None</navType>
    <name>Developer Relations News</name>
  </response>
</IglooApiResponse>

Take note of the id (100498). This id will be used to create a category in our new category class. 

Adding a category using the API

To programmatically add a Category, you can make a POST to /.api/api.svc/categories/add and pass 'name' and the 'category class id' like this:

POST /.api/api.svc/categories/add?name=Technical%20Article&categoryClassId=100498

The response will return something similar to this:

<IglooApiResponse xmlns="http://schemas.iglooplatform.com/Igloo.Old.Common" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <minRequestPeriod>0</minRequestPeriod>
  <requestSupportCode>637049622176790283</requestSupportCode>
  <dictionary i:nil="true" xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
  <response i:type="category">
    <id>668024</id>
    <href/>
    <navType>None</navType>
    <name>Technical Article</name>
    <ClassID>100498</ClassID>
  </response>
</IglooApiResponse>

Once again, we have some important information here. We've created a Category called "Technical Article" and it has been given an id of '668024'.

Adding a category to an object using the API

We discussed Object IDs in a previous post, (Querying digital workplace objects by their URL path) and we can use the same object id to add our new (or an existing, if you prefer) Category to an object. In this case, we'll add our category to a blog post.

We used the APIs in the above post to get the ID of a blog post - it's b68c0e1a-2c70-4636-83c2-08d6b77ad5f2.   
We'll use one of our Object APIs and POST  to /.api/api.svc/objects/{objectId}/add_categories to add our category to the post. We'll pass the object id and the category id like so:

POST /.api/api.svc/objects/b68c0e1a-2c70-4636-83c2-08d6b77ad5f2/add_categories?categories=668024"

The call returns a 200 OK and we can now see the article has the "Technical Article" label attached

Further Reading

Be sure to subscribe to our Developer News channel to stay up to date on all the latest news, tips and tricks. And, if you're not already a member of our developer program,  join now!