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:
- 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 |
PATCH | 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. 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 |
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.
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
, recurse
and restoreMode
sub elements.
{
"arguments": {
"dataSet": {
...
},
"recurse": true,
"restoreMode": 1
}
}
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 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.
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.
Validating bulk properties for a role path
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
, recurse
and restoreMode
sub elements.
{
"arguments": {
"dataSet": {
...
},
"recurse": true,
"restoreMode": 1
}
}
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→