api/categories

ROAD categories are used to collect data for a similar purpose. For now categories are used only to specify types of job templates, which can also specify only parts of a job description.

(Template data is documented in Templates Data. For general understand of ROAD data types and especially ROAD jobs, see Jobs Data.)

About Categories

ROAD categories are used to collect data for a similar purpose. For now categories are used only to specify types of job templates, which can also specify only parts of a job description. Every template can be assigned to several templates.

For example all input specifications may be marked with one category group, or all stream input specifications may be in another category group, as well as all recording templates.

Categories and Groups

Categories contain groups, where data items (e.g. templates) can be assigned to. A category is a container containing groups of the same type like e.g. "Recording job", "Input specifications", "ASIO devices", "DPE Tables".

Each group is assigned to exactly one category.

Category Data - Group Data

Groups exist only as part of a category, so ROAD maintains only categories which contain a set of groups.

A category contains some describing information and a list of groups:

CategoryId
Name
Description (optional)
A list of groups, each with
- Name
- Description (optional)

The Name of categories must be unique. An error is being returned after an attempt to add or change a group to have a name which already exists.

Use Cases

Get a list of all categories
Get all groups of a specific category
Add categories and groups
Rename categories and groups
Delete categories and groups
Assign a template to one or more groups (this is part of the templates interface)
Find templates which are

Interface Usage

REST philosophy is a bit different from function-centric thinking. So to fulfill best practices, we use resource-centric interfaces:

URI	Verb	Parameters (optional)	Success Result	Description
categories	GET	(see below)	OK = 200 JSON formatted results list	Get data for all existing categories (completely or specific fields). Examples: <uri>/api/categories <uri>/api/categories?fields=name, groups.groupId, groups.name&skip=0&limit=20 Note: If no matching category is found, the result value is not 404 (not found) - instead an empty results list will be returned.
categories/{categoryId}	GET	(see below)	OK = 200 JSON formatted result	Get an existing category's data (completely or specific fields). Example: <uri>/api/categories/6745e43?fields=name, groups.name Note: If the category is not found, the result value is 404 (not found).
categories	POST	-	Created = 201 { "categoryId" : "3756423" }	Creates a new category object, returning its CategoryId. BODY may contain a json-formatted category.
categories/{categoryId}	PUT	-	OK = 200	Updates an existing category object. BODY contains all data fields which will be updated. Note: If the category is not found, the result value is 404 (not found).
categories/{categoryId}	DELETE	-	OK = 200	Deletes a tecategory mplate Note: If the category is not found, the result value is 404 (not found).

GET: Supported Parameters for categories

Optional Query Parameters (for all GET requests)

Parameter	Description	Example
fields	Limit the response to specified fields	fields=name, groups.name
filter	Search filter. See Query Expressions for a detailed description. See Group Data for fields which are supported by this interface.	filter=name=="Job types"
sort	Sort order. Comma-separated list of sort fields. An optional "asc" or "desc" can be added after each field name (separated by space).	sort=name desc
offset skip	Offset in results list (default: 0) offset and skip are synonymic	offset=100
limit	Limit the result list size (default: 100)	limit=100

Category and Group Data as REST Body

Where category data is transferred with a REST request to ROAD Service or response from ROAD Service, it is formatted as a JSON.

Example JSON

{
  "name": "Job Types",
  "description": "Most common types of ROAD jobs",
  "groups": [
    {
      "name": "Recording",
      "description": "Meaning output to file or database"
    },
    {
      "name": "Playout",
      "description": "Meaning audible output"
    },
    {
      "name": "Transcoding",
      "description": "Meaning input and output is file or database"
    }
  ]
}

JS

Contents