Configuration API documentation version v1.0
http://api.example.com/x-nmos/configuration/{version}
- version: required(v1.0)
Overview
The Configuration API is exposed by each NMOS Device in a system that supports the AMWA NMOS Device Configuration Specification. The API is used to access the NMOS Device's Device Model which is defined according to the AMWA NMOS Control Architecture and AMWA NMOS Control Framework.
Further Documentation
Further normative documentation covering the behaviour of this API is contained in the docs folder of this repository.
Base
get
List of paths available from this API
get /
List of paths available from this API
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Configuration API base resource",
"title": "Configuration API base resource",
"items": {
"type": "string",
"enum": [
"rolePaths/"
]
},
"minItems": 1,
"maxItems": 1,
"uniqueItems": true
}
Example:
[
"rolePaths/"
]
Role Paths
get
Returns the Role Paths of the Device Model. Each rolePath MUST be created by appending NcObject roles starting with the root block and using "." as the delimiter
get /rolePaths
Returns the Role Paths of the Device Model. Each rolePath MUST be created by appending NcObject roles starting with the root block and using "." as the delimiter
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Configuration API /rolePaths base",
"title": "Configuration API /rolePaths base",
"items": {
"type": "string"
},
"uniqueItems": true
}
Example:
[
"root/",
"root.ClassManager/",
"root.DeviceManager/",
"root.StereoGain/",
"root.StereoGain.LeftChannel/",
"root.StereoGain.RightChannel/"
]
get
Get attributes of the object specified by rolePath
get /rolePaths/{rolePath}
Get attributes of the object specified by rolePath
URI Parameters
- rolePath: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Configuration API /rolePaths/{rolePath}",
"title": "Configuration API /rolePaths/{rolePath}",
"items": {
"type": "string",
"enum": [
"bulkProperties/",
"descriptor/",
"methods/",
"properties/"
]
},
"minItems": 4,
"maxItems": 4,
"uniqueItems": true
}
Example:
[
"bulkProperties/",
"descriptor/",
"methods/",
"properties/"
]
HTTP status code 404
Returned when the requested Role Path does not exist. Corresponds to NcMethodStatus code 404.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
get
Get Bulk Properties of the object, returned as a NcMethodResultBulkValuesHolder object.
options
Validate an NcBulkValuesHolder object against the Device Model
put
Set a Bulk Properties object on the Device Model
get /rolePaths/{rolePath}/bulkProperties
Get Bulk Properties of the object, returned as a NcMethodResultBulkValuesHolder object.
URI Parameters
- rolePath: required(string)
Query Parameters
- recurse: required(boolean)
True will get Bulk Properties for this object and all child objects
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Returns a NcMethodResultBulkValuesHolder from a bulkProperties GET",
"title": "NcMethodResultBulkValuesHolder"
}
Example:
{
"status": 200,
"validationFingerprint": null,
"values": [
{
"rolePath": [ "root", "stereo-gain" ],
"values": [
{
"id": {
"level": 1,
"index": 6
},
"name": "userLabel",
"isReadOnly": false,
"value": "this is the property value"
},
{
"id": {
"level": 2,
"index": 1
},
"name": "enabled",
"isReadOnly": false,
"value": true
}
]
}
]
}options /rolePaths/{rolePath}/bulkProperties
Validate an NcBulkValuesHolder object against the Device Model
URI Parameters
- rolePath: required(string)
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "OPTIONS request body for invoking ValidateSetPropertiesByPath method on NcBulkPropertiesManager",
"title": "Bulk properties Validate request",
"required": [
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"description": "Method arguments. The rolePath is offered in the URL and is not part of these arguments",
"properties": {
"dataSet": {
"type": "object",
"description": "NcBulkValuesHolder datatype"
},
"recurse": {
"type": "boolean"
}
}
}
}
}
Example:
{
"arguments": {
"dataSet": {
"validationFingerprint": null,
"values": [
{
"rolePath": [ "root", "stereo-gain" ],
"values": [
{
"id": {
"level": 1,
"index": 6
},
"name": "userLabel",
"isReadOnly": false,
"value": "Stereo Gain Block"
},
{
"id": {
"level": 2,
"index": 1
},
"name": "enabled",
"isReadOnly": false,
"value": true
}
]
},
{
"rolePath": [ "root", "channel-gain" ],
"values": [
{
"id": {
"level": 1,
"index": 6
},
"name": "userLabel",
"isReadOnly": false,
"value": "Channel Gain Block"
},
{
"id": {
"level": 2,
"index": 1
},
"name": "enabled",
"isReadOnly": false,
"value": true
}
]
}
]
},
"recurse": false
}
}
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties OPTIONS",
"title": "NcMethodResultObjectPropertiesSetValidation"
}
Example:
{
"value": [
{
"rolePath": [ "root", "stereo-gain" ],
"status": 200,
"statusMessage": "OK"
},
{
"rolePath": [ "root", "channel-gain" ],
"status": 200,
"statusMessage": "OK"
}
]
}
put /rolePaths/{rolePath}/bulkProperties
Set a Bulk Properties object on the Device Model
URI Parameters
- rolePath: required(string)
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "PUT request body for invoking SetPropertiesByPath method on NcBulkPropertiesManager",
"title": "Bulk properties Set request",
"required": [
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"description": "Method arguments. The rolePath is offered in the URL and is not part of these arguments",
"properties": {
"dataSet": {
"type": "object",
"description": "NcBulkValuesHolder datatype"
},
"recurse": {
"type": "boolean"
}
}
}
}
}Example:
{
"arguments": {
"dataSet": {
"validationFingerprint": null,
"values": [
{
"rolePath": [ "root", "stereo-gain" ],
"values": [
{
"id": {
"level": 1,
"index": 6
},
"name": "userLabel",
"isReadOnly": false,
"value": "Stereo Gain Block"
},
{
"id": {
"level": 2,
"index": 1
},
"name": "enabled",
"isReadOnly": false,
"value": true
}
]
},
{
"rolePath": [ "root", "channel-gain" ],
"values": [
{
"id": {
"level": 1,
"index": 6
},
"name": "userLabel",
"isReadOnly": false,
"value": "Channel Gain Block"
},
{
"id": {
"level": 2,
"index": 1
},
"name": "enabled",
"isReadOnly": false,
"value": true
}
]
}
]
},
"recurse": false
}
}
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties PUT",
"title": "NcMethodResultObjectPropertiesSetValidation"
}
Example:
{
"value": [
{
"rolePath": [ "root", "stereo-gain" ],
"status": 200,
"statusMessage": "OK"
},
{
"rolePath": [ "root", "channel-gain" ],
"status": 200,
"statusMessage": "OK"
}
]
}
get
Get MS-05 Class Descriptor of this object. This descriptor MUST include all inherited elements
get /rolePaths/{rolePath}/descriptor
Get MS-05 Class Descriptor of this object. This descriptor MUST include all inherited elements
URI Parameters
- rolePath: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultClassDescriptor",
"title": "NcMethodResultClassDescriptor"
}
Example:
{
"status": 200,
"value": {
"description": "NcObject class descriptor",
"classId": [
1
],
"name": "NcObject",
"fixedRole": null,
"properties": [
{
"description": "Static value. All instances of the same class will have the same identity value",
"id": {
"level": 1,
"index": 1
},
"name": "classId",
"typeName": "NcClassId",
"isReadOnly": true,
"isNullable": false,
"isSequence": false,
"isDeprecated": false,
"constraints": null
},
{
"description": "Object identifier",
"id": {
"level": 1,
"index": 2
},
"name": "oid",
"typeName": "NcOid",
"isReadOnly": true,
"isNullable": false,
"isSequence": false,
"isDeprecated": false,
"constraints": null
},
{
"description": "TRUE iff OID is hardwired into device",
"id": {
"level": 1,
"index": 3
},
"name": "constantOid",
"typeName": "NcBoolean",
"isReadOnly": true,
"isNullable": false,
"isSequence": false,
"isDeprecated": false,
"constraints": null
},
{
"description": "OID of containing block. Can only ever be null for the root block",
"id": {
"level": 1,
"index": 4
},
"name": "owner",
"typeName": "NcOid",
"isReadOnly": true,
"isNullable": true,
"isSequence": false,
"isDeprecated": false,
"constraints": null
},
{
"description": "Role of object in the containing block",
"id": {
"level": 1,
"index": 5
},
"name": "role",
"typeName": "NcString",
"isReadOnly": true,
"isNullable": false,
"isSequence": false,
"isDeprecated": false,
"constraints": null
},
{
"description": "Scribble strip",
"id": {
"level": 1,
"index": 6
},
"name": "userLabel",
"typeName": "NcString",
"isReadOnly": false,
"isNullable": true,
"isSequence": false,
"isDeprecated": false,
"constraints": null
},
{
"description": "Touchpoints to other contexts",
"id": {
"level": 1,
"index": 7
},
"name": "touchpoints",
"typeName": "NcTouchpoint",
"isReadOnly": true,
"isNullable": true,
"isSequence": true,
"isDeprecated": false,
"constraints": null
},
{
"description": "Runtime property constraints",
"id": {
"level": 1,
"index": 8
},
"name": "runtimePropertyConstraints",
"typeName": "NcPropertyConstraints",
"isReadOnly": true,
"isNullable": true,
"isSequence": true,
"isDeprecated": false,
"constraints": null
}
],
"methods": [
{
"description": "Get property value",
"id": {
"level": 1,
"index": 1
},
"name": "Get",
"resultDatatype": "NcMethodResultPropertyValue",
"parameters": [
{
"description": "Property id",
"name": "id",
"typeName": "NcPropertyId",
"isNullable": false,
"isSequence": false,
"constraints": null
}
],
"isDeprecated": false
},
{
"description": "Set property value",
"id": {
"level": 1,
"index": 2
},
"name": "Set",
"resultDatatype": "NcMethodResult",
"parameters": [
{
"description": "Property id",
"name": "id",
"typeName": "NcPropertyId",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "Property value",
"name": "value",
"typeName": null,
"isNullable": true,
"isSequence": false,
"constraints": null
}
],
"isDeprecated": false
},
{
"description": "Get sequence item",
"id": {
"level": 1,
"index": 3
},
"name": "GetSequenceItem",
"resultDatatype": "NcMethodResultPropertyValue",
"parameters": [
{
"description": "Property id",
"name": "id",
"typeName": "NcPropertyId",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "Index of item in the sequence",
"name": "index",
"typeName": "NcId",
"isNullable": false,
"isSequence": false,
"constraints": null
}
],
"isDeprecated": false
},
{
"description": "Set sequence item value",
"id": {
"level": 1,
"index": 4
},
"name": "SetSequenceItem",
"resultDatatype": "NcMethodResult",
"parameters": [
{
"description": "Property id",
"name": "id",
"typeName": "NcPropertyId",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "Index of item in the sequence",
"name": "index",
"typeName": "NcId",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "Value",
"name": "value",
"typeName": null,
"isNullable": true,
"isSequence": false,
"constraints": null
}
],
"isDeprecated": false
},
{
"description": "Add item to sequence",
"id": {
"level": 1,
"index": 5
},
"name": "AddSequenceItem",
"resultDatatype": "NcMethodResultId",
"parameters": [
{
"description": "Property id",
"name": "id",
"typeName": "NcPropertyId",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "Value",
"name": "value",
"typeName": null,
"isNullable": true,
"isSequence": false,
"constraints": null
}
],
"isDeprecated": false
},
{
"description": "Delete sequence item",
"id": {
"level": 1,
"index": 6
},
"name": "RemoveSequenceItem",
"resultDatatype": "NcMethodResult",
"parameters": [
{
"description": "Property id",
"name": "id",
"typeName": "NcPropertyId",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "Index of item in the sequence",
"name": "index",
"typeName": "NcId",
"isNullable": false,
"isSequence": false,
"constraints": null
}
],
"isDeprecated": false
},
{
"description": "Get sequence length",
"id": {
"level": 1,
"index": 7
},
"name": "GetSequenceLength",
"resultDatatype": "NcMethodResultLength",
"parameters": [
{
"description": "Property id",
"name": "id",
"typeName": "NcPropertyId",
"isNullable": false,
"isSequence": false,
"constraints": null
}
],
"isDeprecated": false
}
],
"events": [
{
"description": "Property changed event",
"id": {
"level": 1,
"index": 1
},
"name": "PropertyChanged",
"eventDatatype": "NcPropertyChangedEventData",
"isDeprecated": false
}
]
}
}
HTTP status code 500
Returned when the Class Descriptor of this object was unable to be retrieved. Corresponds to NcMethodStatus code 500.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
get
Get Methods of this object. This response MUST include all object methods including all the inherited methods
get /rolePaths/{rolePath}/methods
Get Methods of this object. This response MUST include all object methods including all the inherited methods
URI Parameters
- rolePath: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Configuration API /rolePaths/{rolePath}/methods base",
"title": "Configuration API /rolePaths/{rolePath}/methods base",
"items": {
"type": "string",
"pattern": "^[0-9]+m[0-9]+"
},
"uniqueItems": true
}
Example:
[
"1m1/",
"1m2/",
"1m3/",
"1m4/",
"1m5/",
"1m6/"
]
patch
Invoke method.
patch /rolePaths/{rolePath}/methods/{methodId}
Invoke method.
URI Parameters
- rolePath: required(string)
- methodId: required(string - pattern: ^[0-9]+m[0-9]+)
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "PATCH request body for invoking a method",
"title": "Invoke method body",
"required": [
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"description": "Method arguments. Arguments are specified as nested properties inside this object and their types are dictated by the specific MS-05-02 model for the method targeted. For methods which do not have arguments defined the object MUST be an empty object."
}
}
}
Example:
{
"arguments": {
"id": {
"level": 1,
"index": 6
}
}
}
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResult",
"title": "NcMethodResult"
}
Example:
{
"status": 200,
"value": "user label string"
}
HTTP status code 400
Returned when the method arguments are invalid. Corresponds to NcMethodStatus code 417.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
HTTP status code 404
Returned when the requested Method does not exist. Corresponds to NcMethodStatus code 501.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
HTTP status code 500
Returned when the Method was unable to be invoked. Corresponds to NcMethodStatus code 500.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
get
Get Properties of the object. This response MUST include all object properties including all the inherited properties
get /rolePaths/{rolePath}/properties
Get Properties of the object. This response MUST include all object properties including all the inherited properties
URI Parameters
- rolePath: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Configuration API /rolePaths/{rolePath}/properties base",
"title": "Configuration API /rolePaths/{rolePath}/properties base",
"items": {
"type": "string",
"pattern": "^[0-9]+p[0-9]+"
},
"uniqueItems": true
}
Example:
[
"1p1/",
"1p2/",
"1p3/",
"1p4/",
"1p5/",
"1p6/"
]
get
Get attributes of a Property
get /rolePaths/{rolePath}/properties/{propertyId}
Get attributes of a Property
URI Parameters
- rolePath: required(string)
- propertyId: required(string - pattern: ^[0-9]+p[0-9]+)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Configuration API /rolePaths/{rolePath}/properties/{propertyId}",
"title": "Configuration API /rolePaths/{rolePath}/properties/{propertyId}",
"items": {
"type": "string",
"enum": [
"descriptor/",
"value/"
]
},
"minItems": 2,
"maxItems": 2,
"uniqueItems": true
}
Example:
[
"descriptor/",
"value/"
]
HTTP status code 404
Returned when the requested Property does not exist. Corresponds to NcMethodStatus code 502.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
get
Get MS-05 Datatype Descriptor of property. This descriptor MUST include all inherited elements
get /rolePaths/{rolePath}/properties/{propertyId}/descriptor
Get MS-05 Datatype Descriptor of property. This descriptor MUST include all inherited elements
URI Parameters
- rolePath: required(string)
- propertyId: required(string - pattern: ^[0-9]+p[0-9]+)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultDatatypeDescriptor",
"title": "NcMethodResultDatatypeDescriptor"
}
Example:
{
"status": 200,
"value": {
"description": "Descriptor which is specific to a block member",
"name": "NcBlockMemberDescriptor",
"type": 2,
"fields": [
{
"description": "Role of member in its containing block",
"name": "role",
"typeName": "NcString",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "OID of member",
"name": "oid",
"typeName": "NcOid",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "TRUE iff member's OID is hardwired into device",
"name": "constantOid",
"typeName": "NcBoolean",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "Class ID",
"name": "classId",
"typeName": "NcClassId",
"isNullable": false,
"isSequence": false,
"constraints": null
},
{
"description": "User label",
"name": "userLabel",
"typeName": "NcString",
"isNullable": true,
"isSequence": false,
"constraints": null
},
{
"description": "Containing block's OID",
"name": "owner",
"typeName": "NcOid",
"isNullable": false,
"isSequence": false,
"constraints": null
}
],
"parentType": "NcDescriptor",
"constraints": null
}
}
HTTP status code 500
Returned when the Datatype Descriptor of this object was unable to be retrieved. Corresponds to NcMethodStatus code 500.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
get
Get value of a Property
put
get /rolePaths/{rolePath}/properties/{propertyId}/value
Get value of a Property
URI Parameters
- rolePath: required(string)
- propertyId: required(string - pattern: ^[0-9]+p[0-9]+)
HTTP status code 200
Body
Media type: application/json
Type:
{
"type": "object",
"description": "NcMethodResultPropertyValue with the contents of the property",
"title": "NcMethodResultPropertyValue"
}
Example:
{
"status": 200,
"value": "this is the property value"
}
HTTP status code 500
Returned when the Property was unable to be retrieved. Corresponds to NcMethodStatus code 500.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}
put /rolePaths/{rolePath}/properties/{propertyId}/value
URI Parameters
- rolePath: required(string)
- propertyId: required(string - pattern: ^[0-9]+p[0-9]+)
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "PUT request body for modyfing a property",
"title": "Modify property body",
"required": [
"value"
],
"properties": {
"value": {
"description": "New property value. The actual type is determined by the property's MS-05-02 datatype.",
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "object"
},
{
"type": "array"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
}
Example:
{
"value": 42
}
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResult",
"title": "NcMethodResult"
}
Example:
{
"status": 200
}
HTTP status code 500
Returned when the Property was unable to be set. Corresponds to the following NcMethodStatus codes: 405 if Property is read only, 417 if the value being PUT is invalid, 500 for all other reasons.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "NcMethodResultError",
"title": "NcMethodResultError"
}