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 returns all the role paths available for the device. 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:
- propertyLevel - number representing the inheritance level of the class containing the property (see Control Classes)
- propertyIndex - number representing the index level of the property within the specified inheritance level (see Control Classes)
Method identifiers are fined as {methodLevel}m{methodIndex} where:
- methodLevel - number representing the inheritance level of the class containing the method (see Control Classes)
- methodIndex - number representing the index level of the method within the specified inheritance level (see Control Classes)
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 |
| OPTIONS | Validating bulk properties for a role path | baseUrl/rolePaths/{rolePath}/bulkProperties | bulkProperties-validate-request | NcMethodResultObjectPropertiesSetValidation |
GET
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 |
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 |
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 |
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.
This is equivalent to invoking the GetPropertiesByPath method on the Bulk properties manager object.
PUT
Changing 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.
TODO: Figure out how we map deprecation statuses for properties and methods.
Setting bulk properties for a role path
 |
|---|
| 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
}
}
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.
This is equivalent to invoking the SetPropertiesByPath method inside the Bulk properties manager object.
PATCH
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.
OPTIONS
Validating bulk properties for a role path
 |
|---|
| Validating bulk properties |
The OPTIONS 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→