Merge pull request #22 from AMWA-TV/publish-backup-restore

Merge overall sprint work into main branch
AMWA-TV · Oct 29, 2024 · a6a204c · a6a204c
2 parents c35423a + 5e6f0ed
commit a6a204c
Show file tree

Hide file tree

Showing 16 changed files with 210 additions and 24 deletions.
diff --git a/APIs/schemas/bulkProperties-set-request.json b/APIs/schemas/bulkProperties-set-request.json
@@ -17,6 +17,10 @@
         },
         "recurse": {
           "type": "boolean"
+        },
+        "restoreMode": {
+          "type": "integer",
+          "description": "numeric representation of NcRestoreMode enum options"
         }
       }
     }

diff --git a/APIs/schemas/bulkProperties-validate-request.json b/APIs/schemas/bulkProperties-validate-request.json
@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
-  "description": "OPTIONS request body for invoking ValidateSetPropertiesByPath method on NcBulkPropertiesManager",
+  "description": "PATCH request body for invoking ValidateSetPropertiesByPath method on NcBulkPropertiesManager",
   "title": "Bulk properties Validate request",
   "required": [
     "arguments"
@@ -17,6 +17,10 @@
         },
         "recurse": {
           "type": "boolean"
+        },
+        "restoreMode": {
+          "type": "integer",
+          "description": "numeric representation of NcRestoreMode enum options"
         }
       }
     }

diff --git a/APIs/schemas/bulkProperties-validate-response.json b/APIs/schemas/bulkProperties-validate-response.json
@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
-  "description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties OPTIONS",
+  "description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties PATCH",
   "title": "NcMethodResultObjectPropertiesSetValidation"
 }
diff --git a/docs/API requests.md b/docs/API requests.md
@@ -10,9 +10,9 @@ Concurrency control is left to specific device implementations, however devices
 
 The URL provided in the [IS-04 device](IS-04%20interactions.md) is used as the base URL for all subsequent requests.
 
-As described in the Configuration API, the [rolePaths](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/ConfigurationAPI.html#rolepaths_get) endpoint returns all the role paths available for the device. Each `rolePath` MUST be created by appending [NcObject roles](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html) starting with the `root block` and using `.` as the delimiter. Consequently the `.` character MUST not be used inside individual object roles.
+As described in the Configuration API, the [rolePaths](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/ConfigurationAPI.html#rolepaths_get) endpoint MUST return all the device model's role paths. Each `rolePath` MUST be created by appending [NcObject roles](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html) 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](https://www.ietf.org/rfc/rfc3986.txt). 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.
+It is RECOMMENDED for device model objects roles to use `Unreserved Characters` as described in [RFC 3986 - 2.3. Unreserved Characters](https://www.ietf.org/rfc/rfc3986.txt). 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](https://datatracker.ietf.org/doc/html/rfc7230#section-2.7.3).
 
@@ -39,7 +39,7 @@ The following subsections define common use cases for the applicable HTTP verbs
 | 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) |
+| PATCH | [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
 
@@ -79,10 +79,16 @@ This is equivalent to invoking the [GetDatatype method](https://specs.amwa.tv/ms
 |:--:|
 | _**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).
+The URL MUST target a specific role path in the device model. This MUST retrieve all the properties of that role path as 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 MUST 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). 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](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkpropertiesmanager).
 
+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](Backup%20&%20restore.md#definitions) 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](Backup%20&%20restore.md#definitions) 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
@@ -99,8 +105,6 @@ The body of the request MUST include an object which includes the new value of t
 
 This is equivalent to invoking the generic [Set method](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html#generic-getter-and-setter) 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](images/set-bulk-properties.png) |
@@ -110,15 +114,16 @@ This is equivalent to invoking the generic [Set method](https://specs.amwa.tv/ms
 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.
+The body of the request MUST include an object which includes an `arguments` object with `dataSet`, `recurse` and `restoreMode` sub elements.
 
 ```json
 {
     "arguments": {
         "dataSet": {
             ...
         },
-        "recurse": true
+        "recurse": true,
+        "restoreMode": 1
     }
 }
 ```
@@ -127,10 +132,12 @@ If the `recurse` value is `true` then the device will attempt to use the provide
 
 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).
+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). 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](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncbulkpropertiesmanager).
 
+Setting properties through the `bulkProperties` endpoint allows a user to perform a restore.
+
 ## PATCH
 
 ### Invoking a method
@@ -158,28 +165,25 @@ 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 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` and `recurse` sub elements.
+The body of the request MUST include an object which includes an `arguments` object with `dataSet`, `recurse` and `restoreMode` sub elements.
 
 ```json
 {
     "arguments": {
         "dataSet": {
             ...
         },
-        "recurse": true
+        "recurse": true,
+        "restoreMode": 1
     }
 }
 ```