From 8be227e53b3d8bfdfa183b60d8578d9cd0dbf667 Mon Sep 17 00:00:00 2001 From: jonathan-r-thorpe <64410119+jonathan-r-thorpe@users.noreply.github.com> Date: Tue, 12 Mar 2024 12:34:15 +0000 Subject: [PATCH] Update API RAML (#8) * Add bulkProperties endpoints * Suggested alternative bulkProperties endpoint * Added schemas for bulkProperties endpoints * Removed examples from bulkProperties * formatting * ...formatting * ......formatting * typos * Updated bulkProperties endpoint * Fixed example paths * Updated rolePath schema. Ordered RAML endpoints alphabetically. * Updated method patch example * Tweaked property endpoint schema and example --- APIs/ConfigurationAPI.raml | 151 +++++++++++------- APIs/schemas/bulkProperties-get-response.json | 6 + APIs/schemas/bulkProperties-set-request.json | 15 ++ APIs/schemas/bulkProperties-set-response.json | 6 + .../bulkProperties-validate-request.json | 15 ++ .../bulkProperties-validate-response.json | 6 + APIs/schemas/property.json | 4 +- APIs/schemas/rolePath.json | 9 +- examples/bulkProperties-get-200.json | 29 ++++ examples/bulkProperties-set-200.json | 14 ++ examples/bulkProperties-set-request.json | 56 +++++++ examples/bulkProperties-validate-200.json | 14 ++ examples/bulkProperties-validate-request.json | 56 +++++++ examples/method-patch-request.json | 4 - examples/property-get-200.json | 4 +- examples/rolePath-get-200.json | 5 +- 16 files changed, 321 insertions(+), 73 deletions(-) create mode 100644 APIs/schemas/bulkProperties-get-response.json create mode 100644 APIs/schemas/bulkProperties-set-request.json create mode 100644 APIs/schemas/bulkProperties-set-response.json create mode 100644 APIs/schemas/bulkProperties-validate-request.json create mode 100644 APIs/schemas/bulkProperties-validate-response.json create mode 100644 examples/bulkProperties-get-200.json create mode 100644 examples/bulkProperties-set-200.json create mode 100644 examples/bulkProperties-set-request.json create mode 100644 examples/bulkProperties-validate-200.json create mode 100644 examples/bulkProperties-validate-request.json diff --git a/APIs/ConfigurationAPI.raml b/APIs/ConfigurationAPI.raml index 100f5fe..2b9b8e2 100644 --- a/APIs/ConfigurationAPI.raml +++ b/APIs/ConfigurationAPI.raml @@ -46,6 +46,85 @@ documentation: description: 'Returned when the requested Role Path does not exist. Corresponds to NcMethodStatus code 404.' body: type: !include schemas/ms05-error.json + /bulkProperties: + displayName: 'Bulk Properties' + get: + description: 'Get Bulk Properties of the object, returned as a NcMethodResultBulkValuesHolder object.' + queryParameters: + recurse: + description: 'True will get Bulk Properties for this object and all child objects' + type: boolean + responses: + 200: + body: + type: !include schemas/bulkProperties-get-response.json + example: !include ../examples/bulkProperties-get-200.json + options: + description: 'Validate an NcBulkValuesHolder object against the Device Model' + body: + type: !include schemas/bulkProperties-validate-request.json + example: !include ../examples/bulkProperties-validate-request.json + responses: + 200: + body: + type: !include schemas/bulkProperties-validate-response.json + example: !include ../examples/bulkProperties-validate-200.json + put: + description: 'Set a Bulk Properties object on the Device Model' + body: + type: !include schemas/bulkProperties-set-request.json + example: !include ../examples/bulkProperties-set-request.json + responses: + 200: + body: + type: !include schemas/bulkProperties-set-response.json + example: !include ../examples/bulkProperties-set-200.json + /descriptor: + displayName: 'Class Descriptor' + get: + description: 'Get MS-05 Class Descriptor of this object. This descriptor MUST include all inherited elements' + responses: + 200: + body: + example: !include ../examples/class-descriptor-get-200.json + type: !include schemas/descriptor-get.json + 500: + description: 'Returned when the Class Descriptor of this object was unable to be retrieved. Corresponds to NcMethodStatus code 500.' + body: + type: !include schemas/ms05-error.json + /methods: + displayName: 'Methods' + get: + description: 'Get Methods of this object. This response MUST include all object methods including all the inherited methods' + responses: + 200: + body: + example: !include ../examples/methods-base-get-200.json + type: !include schemas/methods-base.json + /{methodId}: + displayName: 'Invoke Method.' + patch: + description: 'Invoke method.' + body: + example: !include ../examples/method-patch-request.json + type: !include schemas/method-patch-request.json + responses: + 200: + body: + example: !include ../examples/method-patch-200.json + type: !include schemas/method-patch-response.json + 400: + description: 'Returned when the method arguments are invalid. Corresponds to NcMethodStatus code 417.' + body: + type: !include schemas/ms05-error.json + 404: + description: 'Returned when the requested Method does not exist. Corresponds to NcMethodStatus code 501.' + body: + type: !include schemas/ms05-error.json + 500: + description: 'Returned when the Method was unable to be invoked. Corresponds to NcMethodStatus code 500.' + body: + type: !include schemas/ms05-error.json /properties: displayName: 'Properties' get: @@ -68,6 +147,19 @@ documentation: description: 'Returned when the requested Property does not exist. Corresponds to NcMethodStatus code 502.' body: type: !include schemas/ms05-error.json + /descriptor: + displayName: 'Datatype Descriptor of property' + get: + description: 'Get MS-05 Datatype Descriptor of property. This descriptor MUST include all inherited elements' + responses: + 200: + body: + example: !include ../examples/property-descriptor-get-200.json + type: !include schemas/property-descriptor.json + 500: + description: 'Returned when the Datatype Descriptor of this object was unable to be retrieved. Corresponds to NcMethodStatus code 500.' + body: + type: !include schemas/ms05-error.json /value: displayName: 'Value of a Property' get: @@ -95,62 +187,3 @@ documentation: description: '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: type: !include schemas/ms05-error.json - /descriptor: - displayName: 'Datatype Descriptor of property' - get: - description: 'Get MS-05 Datatype Descriptor of property. This descriptor MUST include all inherited elements' - responses: - 200: - body: - example: !include ../examples/property-descriptor-get-200.json - type: !include schemas/property-descriptor.json - 500: - description: 'Returned when the Datatype Descriptor of this object was unable to be retrieved. Corresponds to NcMethodStatus code 500.' - body: - type: !include schemas/ms05-error.json - /methods: - displayName: 'Methods' - get: - description: 'Get Methods of this object. This response MUST include all object methods including all the inherited methods' - responses: - 200: - body: - example: !include ../examples/methods-base-get-200.json - type: !include schemas/methods-base.json - /{methodId}: - displayName: 'Invoke Method.' - patch: - description: 'Invoke method.' - body: - example: !include ../examples/method-patch-request.json - type: !include schemas/method-patch-request.json - responses: - 200: - body: - example: !include ../examples/method-patch-200.json - type: !include schemas/method-patch-response.json - 400: - description: 'Returned when the method arguments are invalid. Corresponds to NcMethodStatus code 417.' - body: - type: !include schemas/ms05-error.json - 404: - description: 'Returned when the requested Method does not exist. Corresponds to NcMethodStatus code 501.' - body: - type: !include schemas/ms05-error.json - 500: - description: 'Returned when the Method was unable to be invoked. Corresponds to NcMethodStatus code 500.' - body: - type: !include schemas/ms05-error.json - /descriptor: - displayName: 'Class Descriptor' - get: - description: 'Get MS-05 Class Descriptor of this object. This descriptor MUST include all inherited elements' - responses: - 200: - body: - example: !include ../examples/class-descriptor-get-200.json - type: !include schemas/descriptor-get.json - 500: - description: 'Returned when the Class Descriptor of this object was unable to be retrieved. Corresponds to NcMethodStatus code 500.' - body: - type: !include schemas/ms05-error.json diff --git a/APIs/schemas/bulkProperties-get-response.json b/APIs/schemas/bulkProperties-get-response.json new file mode 100644 index 0000000..9ddc05e --- /dev/null +++ b/APIs/schemas/bulkProperties-get-response.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "Returns a NcMethodResultBulkValuesHolder from a bulkProperties GET", + "title": "NcMethodResultBulkValuesHolder" +} diff --git a/APIs/schemas/bulkProperties-set-request.json b/APIs/schemas/bulkProperties-set-request.json new file mode 100644 index 0000000..04c69a0 --- /dev/null +++ b/APIs/schemas/bulkProperties-set-request.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "PUT request body for invoking SetPropertiesByPaths method on NcBulkPropertiesManager", + "title": "SetPropertiesByPaths", + "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." + } + } +} diff --git a/APIs/schemas/bulkProperties-set-response.json b/APIs/schemas/bulkProperties-set-response.json new file mode 100644 index 0000000..6b5885c --- /dev/null +++ b/APIs/schemas/bulkProperties-set-response.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties PUT", + "title": "NcMethodResultObjectPropertiesSetValidation" +} diff --git a/APIs/schemas/bulkProperties-validate-request.json b/APIs/schemas/bulkProperties-validate-request.json new file mode 100644 index 0000000..a645997 --- /dev/null +++ b/APIs/schemas/bulkProperties-validate-request.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "PATCH request body for validating NcBulkValuesHolder object.", + "title": "ValidateSetPropertiesByPaths", + "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." + } + } +} diff --git a/APIs/schemas/bulkProperties-validate-response.json b/APIs/schemas/bulkProperties-validate-response.json new file mode 100644 index 0000000..0a077c2 --- /dev/null +++ b/APIs/schemas/bulkProperties-validate-response.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties OPTIONS", + "title": "NcMethodResultObjectPropertiesSetValidation" +} diff --git a/APIs/schemas/property.json b/APIs/schemas/property.json index 42cc45d..0a53e51 100644 --- a/APIs/schemas/property.json +++ b/APIs/schemas/property.json @@ -6,8 +6,8 @@ "items": { "type": "string", "enum": [ - "value/", - "descriptor/" + "descriptor/", + "value/" ] }, "minItems": 2, diff --git a/APIs/schemas/rolePath.json b/APIs/schemas/rolePath.json index 976cff6..0cafe9c 100644 --- a/APIs/schemas/rolePath.json +++ b/APIs/schemas/rolePath.json @@ -6,12 +6,13 @@ "items": { "type": "string", "enum": [ - "properties/", + "bulkProperties", + "descriptors/", "methods/", - "descriptors/" + "properties/" ] }, - "minItems": 3, - "maxItems": 3, + "minItems": 4, + "maxItems": 4, "uniqueItems": true } diff --git a/examples/bulkProperties-get-200.json b/examples/bulkProperties-get-200.json new file mode 100644 index 0000000..495b1a1 --- /dev/null +++ b/examples/bulkProperties-get-200.json @@ -0,0 +1,29 @@ +{ + "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 + } + ] + } + ] +} \ No newline at end of file diff --git a/examples/bulkProperties-set-200.json b/examples/bulkProperties-set-200.json new file mode 100644 index 0000000..f40025e --- /dev/null +++ b/examples/bulkProperties-set-200.json @@ -0,0 +1,14 @@ +{ + "value": [ + { + "rolePath": [ "root", "stereo-gain" ], + "status": 200, + "statusMessage": "OK" + }, + { + "rolePath": [ "root", "channel-gain" ], + "status": 200, + "statusMessage": "OK" + } + ] +} diff --git a/examples/bulkProperties-set-request.json b/examples/bulkProperties-set-request.json new file mode 100644 index 0000000..0d62a5b --- /dev/null +++ b/examples/bulkProperties-set-request.json @@ -0,0 +1,56 @@ +{ + "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 + } +} diff --git a/examples/bulkProperties-validate-200.json b/examples/bulkProperties-validate-200.json new file mode 100644 index 0000000..f40025e --- /dev/null +++ b/examples/bulkProperties-validate-200.json @@ -0,0 +1,14 @@ +{ + "value": [ + { + "rolePath": [ "root", "stereo-gain" ], + "status": 200, + "statusMessage": "OK" + }, + { + "rolePath": [ "root", "channel-gain" ], + "status": 200, + "statusMessage": "OK" + } + ] +} diff --git a/examples/bulkProperties-validate-request.json b/examples/bulkProperties-validate-request.json new file mode 100644 index 0000000..0d62a5b --- /dev/null +++ b/examples/bulkProperties-validate-request.json @@ -0,0 +1,56 @@ +{ + "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 + } +} diff --git a/examples/method-patch-request.json b/examples/method-patch-request.json index ebc8479..a5225ed 100644 --- a/examples/method-patch-request.json +++ b/examples/method-patch-request.json @@ -1,8 +1,4 @@ { - "methodId": { - "level": 1, - "index": 1 - }, "arguments": { "id": { "level": 1, diff --git a/examples/property-get-200.json b/examples/property-get-200.json index 5f0f5bd..e0a16ed 100644 --- a/examples/property-get-200.json +++ b/examples/property-get-200.json @@ -1,4 +1,4 @@ [ - "value/", - "descriptor/" + "descriptor/", + "value/" ] diff --git a/examples/rolePath-get-200.json b/examples/rolePath-get-200.json index 20d7b4e..8608385 100644 --- a/examples/rolePath-get-200.json +++ b/examples/rolePath-get-200.json @@ -1,5 +1,6 @@ [ - "properties/", + "bulkProperties", + "descriptors/", "methods/", - "descriptors/" + "properties/" ]