Networked Media Open Specifications

API requests

←Security and authorization · Index↑ · Data type marshalling→

The endpoints are documented in the Configuration API.

Control session

Concurrency control is left to specific device implementations, however devices MUST always return relevant error response messages and statuses when there are conflicts, errors or other noteworthy states.

URL and usage

The URL provided in the IS-04 device is used as the base URL for all subsequent requests.

As described in the Configuration API, the rolePaths endpoint MUST return all the device model’s role paths. Each rolePath MUST be created by appending NcObject roles starting with the root block and using . as the delimiter. Consequently the . character MUST not be used inside individual object roles.

It is RECOMMENDED for device model objects roles to use Unreserved Characters as described in RFC 3986 - 2.3. Unreserved Characters. When Reserved Characters are used in an object role, they MUST be URL encoded when included in the rolePaths endpoint and subsequently in a URL.

Device model object roles are case sensitive and thus any rolePaths and URLs which include them are also case sensitive as described in RFC 7230.

Property identifiers are defined as {propertyLevel}p{propertyIndex} where:

Method identifiers are fined as {methodLevel}m{methodIndex} where:

This means for a given base URL the root block can be targeted by using {baseUrl}/root as the URL. Furthermore, the userLabel of the root block can be targeted by using {baseUrl}/rolePaths/root/properties/1p6/value as the URL.

The following subsections define common use cases for the applicable HTTP verbs where resources are located using their associated rolePath.

Verb Scenario URL format Body Response
GET Get a property baseUrl/rolePaths/{rolePath}/properties/{propertyId}/value N/A NcMethodResultPropertyValue with the contents of the property
GET Get class descriptor baseUrl/rolePaths/{rolePath}/descriptor N/A NcMethodResultClassDescriptor
GET Get datatype descriptor baseUrl/rolePaths/{rolePath}/properties/{propertyId}/descriptor N/A NcMethodResultDatatypeDescriptor
GET Getting all the properties of a role path baseUrl/rolePaths/{rolePath}/bulkProperties?recurse={value} N/A NcMethodResultBulkValuesHolder
PUT Modify a property baseUrl/rolePaths/{rolePath}/properties/{propertyId}/value property-value-put-request NcMethodResult
PUT Setting bulk properties for a role path baseUrl/rolePaths/{rolePath}/bulkProperties bulkProperties-set-request NcMethodResultObjectPropertiesSetValidation
PATCH Invoke a method baseUrl/rolePaths/{rolePath}/methods/{methodId} method-patch-request NcMethodResult
PATCH Validating bulk properties for a role path baseUrl/rolePaths/{rolePath}/bulkProperties bulkProperties-validate-request NcMethodResultObjectPropertiesSetValidation

GET

Getting a property

Getting a property
Getting a property

The URL MUST target a specific property of an object by locating the object using its role path and the property using its propertyId. The response MUST be of type NcMethodResultPropertyValue with the contents of that property. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.

This is equivalent to invoking the generic Get method on the specific object for the required property.

Getting the class descriptor of an object

Getting class descriptor
Getting class descriptor

The URL MUST target a specific object in the device model. Devices treat this as a request to retrieve the class descriptor of that object’s class and MUST return a response of type NcMethodResultClassDescriptor with a descriptor which includes all inherited elements. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.

This is equivalent to invoking the GetControlClass method on the Class Manager object and including all inherited elements.

Getting the datatype descriptor of a property

Getting datatype descriptor
Getting datatype descriptor

The URL MUST target a specific property of an object by locating the object using its role path and the property using its propertyId. Devices treat this as a request to retrieve the datatype descriptor of that property and MUST return a response of type NcMethodResultDatatypeDescriptor with a descriptor which includes all inherited elements. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.

This is equivalent to invoking the GetDatatype method on the Class Manager object and including all inherited elements.

Getting all the properties of a role path

Getting bulk properties
Getting bulk properties

The URL MUST target a specific role path in the device model. Devices treat this as a request to retrieve all the properties of that role path inside a bulk values holder and MUST return a response of type NcMethodResultBulkValuesHolder. If the recurse query parameter is set to true then the response will include the values of the target role path as well as any nested role paths. Not including the recurse query parameter MUST be treated as providing a recurse value of true. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString. If devices cannot accept backup requests due to temporary internal constraints (e.g. requires to be in maintenance mode) then they MUST use a status of NotReady and supply further details on the reason for this in the errorMessage.

This is equivalent to invoking the GetPropertiesByPath method on the Bulk properties manager object.

Retrieving properties through the bulkProperties endpoint allows a user to perform a full backup or a partial backup.

A full backup is a backup data set returned by a GET operation on the /bulkProperties endpoint of the root block with the recurse parameter set to true.

A partial backup is a backup data set returned by a GET operation on the /bulkProperties endpoint of any object of the device model, other than the root block. A partial backup can also be obtained by a GET operation on the /bulkProperties endpoint of the root block with the recurse query parameter set to false; however this will only result in a backup of the root block only.

PUT

Changing a property

Putting a property
Putting a property

The PUT verb MUST be used for setting individual object properties.

The URL MUST target a specific property of an object by locating the object using its role path and the property using its propertyId. The response MUST be of type NcMethodResult. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.

The body of the request MUST include an object which includes the new value of the property as per the property-value-put-request schema.

This is equivalent to invoking the generic Set method on the specific object for the required property.

TBD: Figure out how we map deprecation statuses for properties and methods.

Setting bulk properties for a role path

Setting bulk properties
Setting bulk properties

The PUT verb MUST be used for setting a bulk properties data set.

The URL MUST target a specific role path. The body of the request MUST include an object which includes an arguments object with dataSet and recurse sub elements.

{
    "arguments": {
        "dataSet": {
            ...
        },
        "recurse": true,
        "allowIncomplete": true
    }
}

If the recurse value is true then the device will attempt to use the provided dataSet to set the properties of the target role path and all nested role paths.

For a full schema of the required body object see the bulkProperties-set-request schema.

The response MUST be of type NcMethodResultObjectPropertiesSetValidation. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString. If devices cannot accept restore requests due to temporary internal constraints (e.g. requires to be in maintenance mode) then they MUST use a status of NotReady and supply further details on the reason for this in the errorMessage.

This is equivalent to invoking the SetPropertiesByPath method inside the Bulk properties manager object.

Setting properties through the bulkProperties endpoint allows a user to perform a restore or a selective restore. The restore action can result in a complete restore or an incomplete restore.

A complete restore occurs when a full backup is applied as a PUT to the /bulkProperties endpoint of the root block with the recurse argument set to true, and all the properties of all role paths in the data set are applied successfully (their returned validation status is Ok). A complete restore can also occur when a partial backup is applied and all the properties of all role paths in the data set are applied successfully (their returned validation status is Ok). An incomplete restore occurs when any of the properties restored returns a validation status other than Ok.

A selective restore is a restore in which a full backup or a partial backup is applied as a PUT to the /bulkProperties endpoint of a role path which is not the root block. A selective restore can also be achieved by a PUT operation to the /bulkProperties endpoint of the root block with the recurse query parameter set to false which will result in restoring the properties of the root block only.

PATCH

Invoking a method

Invoking a method
Invoking a method

The PATCH verb MUST be used for invoking object methods.

The URL MUST target a specific object by locating the object using its role path. The body of the request MUST include an object which includes an arguments object. For methods which do not have arguments defined the request body MUST include an empty arguments object.

{
    "arguments": {
        ...
    }
}

For a full schema of the required body object see the method-patch-request schema.

The response MUST be of type NcMethodResult or a derived type. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.

This is equivalent to invoking the specified method.

TODO: Figure out how we map deprecation statuses for properties and methods.

Validating bulk properties for a role path

Validating bulk properties
Validating bulk properties

The PATCH verb MUST be used for validating a bulk properties data set.

The URL MUST target a specific role path. The body of the request MUST include an object which includes an arguments object with dataSet and recurse sub elements.

{
    "arguments": {
        "dataSet": {
            ...
        },
        "recurse": true
    }
}

If the recurse value is true then the device will attempt to use the provided dataSet to validate the target role path and all nested role paths.

For a full schema of the required body object see the bulkProperties-validate-request schema.

The response MUST be of type NcMethodResultObjectPropertiesSetValidation. If the request encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.

This is equivalent to invoking the ValidateSetPropertiesByPath method inside the Bulk properties manager object.

←Security and authorization · Index↑ · Data type marshalling→