diff --git a/APIs/schemas/bulkProperties-set-request.json b/APIs/schemas/bulkProperties-set-request.json index 04c69a0..4603b22 100644 --- a/APIs/schemas/bulkProperties-set-request.json +++ b/APIs/schemas/bulkProperties-set-request.json @@ -1,15 +1,24 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "description": "PUT request body for invoking SetPropertiesByPaths method on NcBulkPropertiesManager", - "title": "SetPropertiesByPaths", + "description": "PUT request body for invoking SetPropertiesByPath method on NcBulkPropertiesManager", + "title": "Bulk properties Set request", "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. Arguments only need to be included for methods which have arguments and MUST be omitted if the method does not require any arguments." + "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" + } + } } } -} +} \ No newline at end of file diff --git a/APIs/schemas/bulkProperties-validate-request.json b/APIs/schemas/bulkProperties-validate-request.json index a645997..7796c1c 100644 --- a/APIs/schemas/bulkProperties-validate-request.json +++ b/APIs/schemas/bulkProperties-validate-request.json @@ -1,15 +1,24 @@ { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", - "description": "PATCH request body for validating NcBulkValuesHolder object.", - "title": "ValidateSetPropertiesByPaths", + "description": "OPTIONS request body for invoking ValidateSetPropertiesByPath method on NcBulkPropertiesManager", + "title": "Bulk properties Validate request", "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. Arguments only need to be included for methods which have arguments and MUST be omitted if the method does not require any arguments." + "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" + } + } } } } diff --git a/docs/API requests.md b/docs/API requests.md index bc2963e..df48b2c 100644 --- a/docs/API requests.md +++ b/docs/API requests.md @@ -30,13 +30,16 @@ This means for a given base URL the `root` block can be targeted by using `{base 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](#getting-a-property) | baseUrl/rolePaths/{rolePath}/properties/{propertyId}/value | N/A | [NcMethodResultPropertyValue](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresultpropertyvalue) with the contents of the property | -| GET | [Get class descriptor](#getting-the-class-descriptor-of-an-object) | baseUrl/rolePaths/{rolePath}/descriptor | N/A | [NcMethodResultClassDescriptor](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresultclassdescriptor) | -| GET | [Get datatype descriptor](#getting-the-datatype-descriptor-of-a-property) | baseUrl/rolePaths/{rolePath}/properties/{propertyId}/descriptor | N/A | [NcMethodResultDatatypeDescriptor](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresultdatatypedescriptor) | -| PUT | [Modify a property](#put) | baseUrl/rolePaths/{rolePath}/properties/{propertyId}/value | [property-value-put-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/property-value-put-request.json) | [NcMethodResult](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresult) | -| PATCH | [Invoke a method](#patch) | baseUrl/rolePaths/{rolePath}/methods/{methodId} | [method-patch-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/method-patch-request.json) | [NcMethodResult](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresult) | +| Verb | Scenario | URL format | Body | Response | +| ------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| GET | [Get a property](#getting-a-property) | baseUrl/rolePaths/{rolePath}/properties/{propertyId}/value | N/A | [NcMethodResultPropertyValue](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresultpropertyvalue) with the contents of the property | +| GET | [Get class descriptor](#getting-the-class-descriptor-of-an-object) | baseUrl/rolePaths/{rolePath}/descriptor | N/A | [NcMethodResultClassDescriptor](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresultclassdescriptor) | +| GET | [Get datatype descriptor](#getting-the-datatype-descriptor-of-a-property) | baseUrl/rolePaths/{rolePath}/properties/{propertyId}/descriptor | N/A | [NcMethodResultDatatypeDescriptor](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresultdatatypedescriptor) | +| GET | [Getting all the properties of a role path](#getting-all-the-properties-of-a-role-path) | baseUrl/rolePaths/{rolePath}/bulkProperties?recurse={value} | N/A | [NcMethodResultBulkValuesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultbulkvaluesholder) | +| PUT | [Modify a property](#changing-a-property) | baseUrl/rolePaths/{rolePath}/properties/{propertyId}/value | [property-value-put-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/property-value-put-request.json) | [NcMethodResult](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresult) | +| PUT | [Setting bulk properties for a role path](#setting-bulk-properties-for-a-role-path) | baseUrl/rolePaths/{rolePath}/bulkProperties | [bulkProperties-set-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-set-request.json) | [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation) | +| PATCH | [Invoke a method](#invoking-a-method) | baseUrl/rolePaths/{rolePath}/methods/{methodId} | [method-patch-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/method-patch-request.json) | [NcMethodResult](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresult) | +| OPTIONS | [Validating bulk properties for a role path](#validating-bulk-properties-for-a-role-path) | baseUrl/rolePaths/{rolePath}/bulkProperties | [bulkProperties-validate-request](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-validate-request.json) | [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation) | ## GET @@ -70,13 +73,25 @@ The URL MUST target a specific property of an object by locating the object usin This is equivalent to invoking the [GetDatatype method](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncclassmanager) on the [Class Manager object](https://specs.amwa.tv/ms-05-02/latest/docs/Managers.html#class-manager) and including all inherited elements. +### Getting all the properties of a role path + +| ![Getting bulk properties](images/getting-bulk-properties.png) | +|:--:| +| _**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](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkvaluesholder) and MUST return a response of type [NcMethodResultBulkValuesHolder](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#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](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an errorMessage of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). + +This is equivalent to invoking the `GetPropertiesByPath` method on the [Bulk properties manager object](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkpropertiesmanager). + ## PUT +### Changing a property + | ![Putting a property](images/putting-a-property.png) | |:--:| | _**Putting a property**_ | -The PUT verb MUST only be used for setting individual object properties. +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](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresult). If the request encountered an error then the response result returned MUST inherit from [NcMethodResultError](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an errorMessage of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). @@ -86,13 +101,45 @@ This is equivalent to invoking the generic [Set method](https://specs.amwa.tv/ms `TODO`: Figure out how we map deprecation statuses for properties and methods. +### Setting bulk properties for a role path + +| ![Setting bulk properties](images/set-bulk-properties.png) | +|:--:| +| _**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. + +```json +{ + "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](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-set-request.json) schema. + +The response MUST be of type [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation). If the request encountered an error then the response result returned MUST inherit from [NcMethodResultError](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an errorMessage of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). + +This is equivalent to invoking the `SetPropertiesByPath` method inside the [Bulk properties manager object](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkpropertiesmanager). + ## PATCH +### Invoking a method + | ![Invoking a method](images/invoking-a-method.png) | |:--:| | _**Invoking a method**_ | -The PATCH verb MUST only be used for invoking object methods. +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. @@ -112,3 +159,35 @@ The response MUST be of type [NcMethodResult](https://specs.amwa.tv/ms-05-02/lat 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](images/validate-bulk-properties.png) | +|:--:| +| _**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. + +```json +{ + "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](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/schemas/bulkProperties-validate-request.json) schema. + +The response MUST be of type [NcMethodResultObjectPropertiesSetValidation](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncmethodresultobjectpropertiessetvalidation). If the request encountered an error then the response result returned MUST inherit from [NcMethodResultError](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncmethodresulterror) and include an errorMessage of type [NcString](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#primitives). + +This is equivalent to invoking the `ValidateSetPropertiesByPath` method inside the [Bulk properties manager object](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkpropertiesmanager). diff --git a/docs/Overview.md b/docs/Overview.md index 72aedcd..c667c96 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -6,8 +6,6 @@ _(c) AMWA 2023, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_ -![NMOS logo](images/NMOS-logo.png) - ## Introduction This document aims to give a general description of the NMOS Device Configuration API. This API defines how NMOS Control models (described in the NMOS Control Framework) can be exposed and consumed in a standardized way when using HTTP. @@ -22,16 +20,8 @@ This API does not support subscriptions and notifications. For subscriptions and ## Use of Normative Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", -and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119][RFC-2119]. +and "OPTIONAL" in this document are to be interpreted as described in [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119). ## Definitions The NMOS term 'Device' is used as defined in the [NMOS Glossary](https://specs.amwa.tv/nmos/main/docs/Glossary.html). - -This specification also defines the following terms. - -### Example Term - -Example definition - -[RFC-2119]: https://tools.ietf.org/html/rfc2119 "Key words for use in RFCs" diff --git a/docs/images/NMOS-logo.png b/docs/images/NMOS-logo.png deleted file mode 100644 index f831307..0000000 Binary files a/docs/images/NMOS-logo.png and /dev/null differ diff --git a/docs/images/README.md b/docs/images/README.md deleted file mode 100644 index 4bffe21..0000000 --- a/docs/images/README.md +++ /dev/null @@ -1 +0,0 @@ -This directory is for images used in documentation diff --git a/docs/images/getting-bulk-properties.png b/docs/images/getting-bulk-properties.png new file mode 100644 index 0000000..c6eb805 Binary files /dev/null and b/docs/images/getting-bulk-properties.png differ diff --git a/docs/images/set-bulk-properties.png b/docs/images/set-bulk-properties.png new file mode 100644 index 0000000..401869b Binary files /dev/null and b/docs/images/set-bulk-properties.png differ diff --git a/docs/images/validate-bulk-properties.png b/docs/images/validate-bulk-properties.png new file mode 100644 index 0000000..ee38805 Binary files /dev/null and b/docs/images/validate-bulk-properties.png differ