Skip to content

Commit

Permalink
Update API RAML (#8)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
jonathan-r-thorpe authored Mar 12, 2024
1 parent e80ae6f commit 8be227e
Show file tree
Hide file tree
Showing 16 changed files with 321 additions and 73 deletions.
151 changes: 92 additions & 59 deletions APIs/ConfigurationAPI.raml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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
6 changes: 6 additions & 0 deletions APIs/schemas/bulkProperties-get-response.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Returns a NcMethodResultBulkValuesHolder from a bulkProperties GET",
"title": "NcMethodResultBulkValuesHolder"
}
15 changes: 15 additions & 0 deletions APIs/schemas/bulkProperties-set-request.json
Original file line number Diff line number Diff line change
@@ -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."
}
}
}
6 changes: 6 additions & 0 deletions APIs/schemas/bulkProperties-set-response.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties PUT",
"title": "NcMethodResultObjectPropertiesSetValidation"
}
15 changes: 15 additions & 0 deletions APIs/schemas/bulkProperties-validate-request.json
Original file line number Diff line number Diff line change
@@ -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."
}
}
}
6 changes: 6 additions & 0 deletions APIs/schemas/bulkProperties-validate-response.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Returns a NcMethodResultObjectPropertiesSetValidation from a bulkProperties OPTIONS",
"title": "NcMethodResultObjectPropertiesSetValidation"
}
4 changes: 2 additions & 2 deletions APIs/schemas/property.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
"items": {
"type": "string",
"enum": [
"value/",
"descriptor/"
"descriptor/",
"value/"
]
},
"minItems": 2,
Expand Down
9 changes: 5 additions & 4 deletions APIs/schemas/rolePath.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@
"items": {
"type": "string",
"enum": [
"properties/",
"bulkProperties",
"descriptors/",
"methods/",
"descriptors/"
"properties/"
]
},
"minItems": 3,
"maxItems": 3,
"minItems": 4,
"maxItems": 4,
"uniqueItems": true
}
29 changes: 29 additions & 0 deletions examples/bulkProperties-get-200.json
Original file line number Diff line number Diff line change
@@ -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
}
]
}
]
}
14 changes: 14 additions & 0 deletions examples/bulkProperties-set-200.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"value": [
{
"rolePath": [ "root", "stereo-gain" ],
"status": 200,
"statusMessage": "OK"
},
{
"rolePath": [ "root", "channel-gain" ],
"status": 200,
"statusMessage": "OK"
}
]
}
56 changes: 56 additions & 0 deletions examples/bulkProperties-set-request.json
Original file line number Diff line number Diff line change
@@ -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
}
}
14 changes: 14 additions & 0 deletions examples/bulkProperties-validate-200.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"value": [
{
"rolePath": [ "root", "stereo-gain" ],
"status": 200,
"statusMessage": "OK"
},
{
"rolePath": [ "root", "channel-gain" ],
"status": 200,
"statusMessage": "OK"
}
]
}
Loading

0 comments on commit 8be227e

Please sign in to comment.