Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add bulk properties GET/PUT/OPTIONS documentation sections #9

Merged
merged 6 commits into from
Apr 16, 2024
Merged

Add bulk properties GET/PUT/OPTIONS documentation sections #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bf59ca3
Add new diagrams for the bulk properties endpoint
cristian-recoseanu Apr 16, 2024
91c470e
Update set/validate schemas for bulk properties requests
cristian-recoseanu Apr 16, 2024
8b9d9bb
Update API requests.md
cristian-recoseanu Apr 16, 2024
ba7bc9c
Update Overview.md
cristian-recoseanu Apr 16, 2024
6d36163
Update Overview.md
cristian-recoseanu Apr 16, 2024
10ec040
Update API requests.md
cristian-recoseanu Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions APIs/schemas/bulkProperties-set-request.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
}
}
15 changes: 12 additions & 3 deletions APIs/schemas/bulkProperties-validate-request.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
}
}
97 changes: 88 additions & 9 deletions docs/API requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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).

Expand All @@ -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.
Expand All @@ -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).
12 changes: 1 addition & 11 deletions docs/Overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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"
Binary file removed docs/images/NMOS-logo.png
View file
Open in desktop
Binary file not shown.
1 change: 0 additions & 1 deletion docs/images/README.md
View file
Open in desktop

This file was deleted.

Binary file added docs/images/getting-bulk-properties.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/set-bulk-properties.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/validate-bulk-properties.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.