Arlo

REST Pub API: EventTemplateCategories

EventTemplateCategories collection resource can be used to retrieve the metadata of categories used to classify templates. For example, a provider of management events might have categories of "Executive", "Introductory" and "Advanced", each of which may have a number of event templates within it. Categories are organised in a tree-structure with each category having zero or one parent category, allowing for multiple levels of sub-categories. Categories at the top of the tree have no parent.

Example page using API data with a browsable list of categories and template items within each.

This resource is used to support common integration scenarios of showing a list of all categories on a page for visitors to browse through (see screenshot right). This endpoint will retrieve data describing the Leadership, Management and Project Management categories. The EventTemplateCategoryItems resource can then be used to retrieve details of all templates and links within each of these (with a single API call). The combination of both of these API endpoints is used to produce this example.

Each category instance returned by this resource has metadata of a name, description, and URI link, as well as a reference to its parent in the tree (if any).

This resource can return a collection of all available categories (useful for producing navigation lists), or the details of a specific category instance (useful for retrieving data when generating a specific category page). The specification of both is covered in this article.

Note that this resource is used only to retrieve details about the tree structure of categories, with meta details about each node. To retrieve the list of child items within a category (such as links to the templates shown in the screenshot), use the EventTemplateCategoryItems resource.

Category instance resource

Provides access to individual of category instances by ID. Skip to an example request.

Resource URI

/api/2012-02-01/pub/resources/eventtemplatecategories/{id}

General structure

{
   "CategoryID":9037,
   "ParentCategoryID":9015,
   "SequenceIndex":7,
   "Name":"Management Skills",
   "Description":{
      "ContentType":"application/xhtml",
      "Text":"<p>These short courses are aimed at improving your skills in managing staff in large or small teams.</p>"
   },
   "ViewUri":"http://acme.example.org/course-catalogue/9037-management-skills"
}

Item fields

Field Description
CategoryID An integer value that uniquely identifies this resource within the platform.
ParentCategoryID An integer value that identifies the immediate parent of this category in the tree. This field is omitted if the category has no parent (meaning it is a top-level category).
Name A string representing the name of the category, up to 128 characters long.
SequenceIndex An integer value representing the ordinal sort order of this category within its immediate parent. Use this field to ensure child items are correctly sorted within display lists.
Description A structure containing marked-up text representing the description header for this category. This field is often not suitable for display in lists and can contain arbitrary HTML including tables, lists and images.
Structure fields
  • ContentType: String representing the content type of the description header, usually application/xhtml.
  • Text: Text content of the description header.
Footer A structure containing marked-up text representing the description footer for this category. This field is often not suitable for display in lists and can contain arbitrary HTML including tables, lists and images.
Structure fields
  • ContentType: String representing the content type of the description footer, usually application/xhtml.
  • Text: Text content of the description footer.
ViewUri A string representing a URI where more information for this category can be found. This may be an Arlo page, or it may be a custom URI.

HTTP GET

Returns a representation of an individual Event Template Category by ID, including the properties above.

Optional parameters
Parameter Description
format String representing the required response format. Only required if an Accept HTTP header is not provided. Supported values: json

NOTE: If this parameter is missing and no valid Accept header is supplied, the API will return a 406 Not Acceptable response.
callback The script function to call with response data if this call is to be executed as a jsonp request. The HTTP content type for the response will be application/javascript.
fields A list of comma-separated values representing the required fields in the response payload. Supported values (field names) are listed in the item fields section. Field names are not case sensitive. Default is CategoryID,Name,ViewUri
Response

See HTTP response codes and error handling for more information on the possible responses and codes returned by this resource.

Example

Retrieve the details for category with ID 217, including the parent, name, sequence index, description and URI link.

GET /api/2012-02-01/pub/resources/eventtemplatecategories/217/?format=json&fields=ParentCategoryID,Name,SequenceIndex,Description,ViewUri

{
   "ParentCategoryID":201,
   "SequenceIndex":2,
   "Name":"Management Skills",
   "Description":{
      "ContentType":"application/xhtml",
      "Text":"<p>These short courses are aimed at improving your skills in managing staff in large or small teams.</p>"
   },
   "ViewUri":"http://acme.example.org/course-catalogue/9037-management-skills"
}

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.

Category collection resource

Retrieves a flat list of category instances for one or more parent nodes in the category tree. Skip to an example request.

When processing the results, to determine the position of a given category within the overall tree structure, each item in the array includes a ParentCategoryID field indicating the ID of its parent. Elements without this field are top-level categories.

When producing lists of sub-categories, to determine list order within a parent node each item in the collection includes a SequenceIndex field. This field is a number representing the ordinal sort order to use when producing a list of children under a parent category.

Resource URI

/api/2012-02-01/pub/resources/eventtemplatecategories/

General structure

This resource returns a collection entity with a StartIndex, Count and Items collection containing category nodes.

{
   "StartIndex":0,
   "Count":11,
   "Items":[
      {
         "CategoryID":9015,
         "SequenceIndex":0,
         "Name":"Events",
         "ViewUri":"http://demo.learningsource.com.au/course-catalogue"
      },
      {
         "CategoryID":9030,
         "ParentCategoryID":9015,
         "SequenceIndex":1,
         "Name":"Accounting & Finance",
         "ViewUri":"http://demo.learningsource.com.au/course-catalogue/9030-accounting-finance"
      },
      {
         "CategoryID":9038,
         "ParentCategoryID":9037,
         "SequenceIndex":0,
         "Name":"Home",
         "ViewUri":"http://demo.learningsource.com.au/course-catalogue/art-home-and-garden/9038-home"
      },      
      ...
   ]
}

Collection fields

Field Description
StartIndex The start index of the first item in the payload within the overall result set. Used for paging.
Count The number of items returned in the payload in the Items array. This value is different to the total number of results in the overall result set (the TotalCount field). Used in paging and represents the page size.
TotalCount The total number of results in the overall result set. This field is not included unless explicitly requested in the optional parameters.
Items An array of category instance records.

HTTP GET

Returns a collection of all Event Template Category tree nodes, including the properties above.

Optional parameters
Parameter Description
format String representing the required response format. Only required if an Accept HTTP header is not provided. Supported values: json

NOTE: If this parameter is missing and no valid Accept header is supplied, the API will return a 406 Not Acceptable response.
parentCategoryIDs A list of comma-separated values representing the IDs of parent categories to retrieve child categories for. If omitted, all categories will be retrieved.
callback The script function to call with response data if this call is to be executed as a jsonp request. The HTTP content type for the response will be application/javascript.
fields A list of comma-separated values representing the required fields for each record in the response payload. Supported values (field names) are listed in the item fields section. Field names are not case sensitive. Default is CategoryID,Name,ViewUri
skip The number of records to skip in the source results before returning the response payload. Used for paging. Default is 0.
top The maximum number of records to return in the response payload. Used for paging. Default is 20. The maximum supported value is 200.
includeTotalCount Boolean value determining whether an additional property (TotalCount) is included in the response respresenting the total count of matching records on the server, independent of the count of records actually returned in the response payload. Used for paging. Supported values: true, false. Default is false.
Example 1

Retrieve a collection with details of all category nodes in the tree, including their name, parent, index (for sorting) and URI link.

GET /api/2012-02-01/pub/resources/eventtemplatecategories/?format=json&fields=CategoryID,ParentCategoryID,Name,SequenceIndex,ViewUri

Example 2

Retrieve a collection with details of all sub-categories of the parent 107 node in the tree, including their name, index (for sorting) and URI link.

GET /api/2012-02-01/pub/resources/eventtemplatecategories/?format=json&parentcategoryids=107&fields=CategoryID,Name,SequenceIndex,ViewUri

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Not supported.