Networked Media Open Specifications

API requests

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

All request results MUST return a response which inherits from the base NcMethodResult that contains a status of type NcMethodStatus. If the method call encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.

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 (see Error response messages).

URL and query parameters usage

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

The device model of the device can be navigated by appending NcObject roles on top of the base URL starting from the root block and using / as the delimiter.

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 a URL.

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

This means for a given base URL the root block can be targeted by using {baseUrl}/root as the URL.

Query parameters MUST be used to target properties or methods for a particular object located by URL.

This means using the base URL the userLabel of the root block can be targeted by using {baseUrl}/root?level=1&index=6 as the URL.

All HTTP requests map to invoking methods on the resources located by the URL.

The following subsections define use cases for the applicable HTTP verbs where resources are located using a URL format where the following are defined:

Verb Scenario URL format Condition Body Response
GET Get a property {baseUrl}/{rolePath}?level={propertyLevel}&index={propertyIndex} The URL and query parameters target a specific object and property N/A NcMethodResultPropertyValue with the contents of the property
GET Get block members {baseUrl}/{rolePath} The URL targets a specific block N/A NcMethodResultPropertyValue with the contents of the members property
GET Get class descriptor {baseUrl}/{rolePath}?describe=true The URL targets a specific object N/A NcMethodResultClassDescriptor
GET Get datatype descriptor {baseUrl}/{rolePath}?level={propertyLevel}&index={propertyIndex}&describe=true The URL and query parameters target a specific object and property N/A NcMethodResultDatatypeDescriptor
PUT Modify a property {baseUrl}/{rolePath}?level={propertyLevel}&index={propertyIndex} The URL and query parameters target a specific object and property modify-property schema NcMethodResult
PATCH Invoke a method {baseUrl}/{rolePath} The URL targets a specific object invoke-method schema NcMethodResult

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 adding level and index query parameters. The response MUST be of type NcMethodResultPropertyValue with the contents of that property.

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

The following table explains the HTTP status and NcMethodStatus codes and the relevant scenarios.

Scenario HTTP status code NcMethodStatus code
Request is successful 200 200
Object cannot be found using the offered baseUrl and rolePath 404 404
Object is located successfully via rolePath but the desired property located via query parameters does not exist 404 502
The property and object are located successfully but the value cannot be retrieved for any reason 500 500

Getting the members of a block

Getting block members
Getting block members

The URL MUST target a specific block object in the device model and MUST NOT contain any query parameters. Devices MUST treat this as a request to retrieve the members property of that block. The response MUST be of type NcMethodResultPropertyValue with the contents of the members property. The response MUST be the same to the one received when appending the level and index query parameters and targeting the members property as described in Getting a property.

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

The following table explains the HTTP status and NcMethodStatus codes and the relevant scenarios.

Scenario HTTP status code NcMethodStatus code
Request is successful 200 200
Object cannot be found using the offered baseUrl and rolePath 404 404
Object is located successfully via rolePath but the desired property located via query parameters does not exist for example because the object is not a block 404 502
The property and object are located successfully but the value cannot be retrieved for any reason 500 500

Getting the class descriptor of an object

Getting class descriptor
Getting class descriptor

The URL MUST target a specific object in the device model and include the describe=true query parameter. 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.

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

The following table explains the HTTP status and NcMethodStatus codes and the relevant scenarios.

Scenario HTTP status code NcMethodStatus code
Request is successful 200 200
Object cannot be found using the offered baseUrl and rolePath 404 404
Object is located successfully via rolePath but class descriptor cannot be retrieved 500 500

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 adding level, index and describe=true query parameters. 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.

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

The following table explains the HTTP status and NcMethodStatus codes and the relevant scenarios.

Scenario HTTP status code NcMethodStatus code
Request is successful 200 200
Object cannot be found using the offered baseUrl and rolePath 404 404
Object is located successfully via rolePath but the desired property located via query parameters does not exist 404 502
The property and object are located successfully but datatype descriptor cannot be retrieved for any reason 500 500

PUT

Putting a property
Putting a property

The PUT verb MUST only 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 adding level and index query parameters. The response MUST be of type NcMethodResult.

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

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

The following table explains the HTTP status and NcMethodStatus codes and the relevant scenarios.

Scenario HTTP status code NcMethodStatus code
Request is successful 200 200
Object cannot be found using the offered baseUrl and rolePath 404 404
Object is located successfully via rolePath but the desired property located via query parameters does not exist 404 502
The property and object are located successfully but the value cannot be set because it is readonly 500 405
The property and object are located successfully but the value cannot be set because it is not valid 500 417
The property and object are located successfully but the value cannot be set for any other reason 500 500

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

TBD: Do we say for any other error status codes just use 500 as the HTTP status code?

PATCH

Invoking a method
Invoking a method

The PATCH verb MUST only 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 a methodId with level and index followed by any arguments required by the method.

{
    "methodId": {
        "level": ...,
        "index": ...
    },
    "arguments": {
        ...
    }
}

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

The response MUST be of type NcMethodResult or a derived type.

This is equivalent to invoking the specified method.

The following table explains the HTTP status and NcMethodStatus codes and the relevant scenarios.

Scenario HTTP status code NcMethodStatus code
Request is successful 200 200
Object cannot be found using the offered baseUrl and rolePath 404 404
Object is located successfully via rolePath but the desired method does not exist 404 501
The method and object are located successfully but the method cannot be invoked because the arguments are not valid 500 417
The method and object are located successfully but the method cannot be invoked because of any other reason 500 500

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

Error response messages

When any request encounters an error, the response MUST be NcMethodResultError or a derived datatype.

TODO: Capture possible HTTP status codes and NcMethodStatus values for general error responses.

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

Documentation built at 09:23:08 CST on 2023-12-12.
(c) AMWA 2023. RAML/JSON licensed under Apache 2.0. Documentation licensed under CC BY-ND 4.0.