{{!-- A Hack for windows chromium/chrome to not report the file as contentType:text/html but contentType:text/plain--}}   {{!-- --}} {{!-- title page --}}

RSI Bundle Documentation

{{packageInfo.name}}

© by Dr. Patrick Bartsch 2019

 

version: {{packageInfo.version}}

 

{{!-- /title page --}} ## Table of contents * [Description](#descrip) * General Information {{#each this.serviceDefinitions}} * [{{meta.name}}](#{{meta.name}}) {{/each}} * Change Logs * [Bundle](#Changelog) {{#each this.serviceDefinitions}} * [{{meta.name}}](#{{meta.name}}Changelog) {{/each}} * Resources / Object Definitions {{#each this.serviceDefinitions}} {{#each this.spec.resources}} {{!-- iterate over all resources --}} * [/{{extractServiceName ../meta.name}}/{{@key}}](#{{@key}}Object) {{/each}} {{/each}} * Type Definitions {{#each this.serviceDefinitions}} {{#each this.spec.types}} {{!-- iterate over all types --}} * [/{{extractServiceName ../meta.name}}/{{@key}}](#{{@key}}Type) {{/each}} {{/each}} ## Description {{packageInfo.description}} ## Bundle Changelog ``` {{safeString changelog}} ```
{{#each this.serviceDefinitions}} # {{meta.name}} {{meta.description}} ## General information version: {{meta.version}} Repository: {{meta.repository}} Author: {{meta.author.name}} {{#if meta.contributers}} Contributors: {{#each meta.contributers}} * {{this}} {{/each}} {{/if}} ## Changelog ``` {{safeString changelog}} ``` ## Resources / Object Definitions The following section defines the resources available within this service. Resources are collections of `xObjects` and each `Object` has its own `id` and `uri`, so that they can be addressed separately. {{#each spec.resources}} ### {{@key}}Object {{this.description}} ### Attributes | name | description | type | format | unit(s) | value(s) | |------------------------------|------------------------------------------------------------|---------------|---------------|---------------|-----------------------| {{!-- iterate over all attributes of objectModel--}} {{#each this.objectModel.attributes}} | {{strech @key 28}} | {{strech this.description 58}} | {{strech this.type 13 }} | {{strech this.format 13}} | {{strech this.unit 13}} | {{getValue this}} | {{/each}} ## Resource level access (/{{extractServiceName ../meta.name}}/{{@key}}/) {{#each this.accessMethods}} ### {{toUpperCase @key}} Use a {{methodToText @key }} on `/{{extractServiceName ../../meta.name}}/{{@ ../key}}/` to {{resourceLevelAction @key }} [{{@ ../key}}Object](#{{@ ../key}}Object) {{#if this.usesPermissions}} #### Scopes To perform a {{methodToText @key }} on this endpoint, the following scope permissions have to be presented with the `access_token`: {{#each this.usesPermissions }} * {{this}} {{/each}} {{/if}} {{#if this.additionalHeaders}} #### Additional headers The following headers might be sent with the request to transport information which are either transient or do not belong th the object payload but are needed to perform the desired state change. | header | description | type | mandatory | |------------------------------|--------------------------|------|-----------| {{#each this.additionalHeaders }} | {{@key }} | {{this.description}} | {{this.type}} | {{this.isRequired}} | {{/each}} {{/if}} {{#if this.parameters.properties }} #### Parameters The following parameters can be used with the request and/or subscriptions: | name | type | format | mandatory | |------------------------------|---------------|----------------|-----------| {{#each this.parameters.properties }} | {{strech @key 28}} | {{strech this.type 13}} | {{strech this.format 13}} | {{isMandatory @key ../parameters.required 9}} | {{/each}} {{/if}} #### Example {{#ifEqCi @key 'subscribe'}} send to server ```json { "event": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/", "type": "subscribe" } ``` receive a subscription acknowledgement first ```json { "status": "ok", "event": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/", "type": "subscribe" } ``` immediately followed by the initial data message representing current state ```json { "status": "ok", "event": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/", "type": "data", "data": [ { "id": "3901a278-ba17-44d6-9aef-f7ca67c04840", "name": "lorem ipsum", "uri": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840" }, { "id": "8901870-b526-11e3-a5e2-0800200c9a66", "name": "dolor sit", "uri": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/8901870-b526-11e3-a5e2-0800200c9a66" } ] } ``` {{/ifEqCi}} {{#ifnEqCi @key 'SUBSCRIBE'}} *request* ```http {{toUpperCase @key }} /{{extractServiceName ../../../meta.name}}/{{@ ../key}}/ HTTP/1.1 Host: rsi.local:1337 Connection: keep-alive Accept: application/json Authorization: Bearer Accept-Encoding: gzip,deflate {{#ifEqCi @key 'POST'}} { "rsi": "rockz.." } {{/ifEqCi}} ``` *response* {{#ifEqCi @key 'GET'}} ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 ETag: "-32550834" Content-Encoding: gzip Date: Tue, 07 Apr 1980 00:00:00 GMT Connection: keep-alive Transfer-Encoding: chunked { "status": "ok", "data": [ { "id": "3901a278-ba17-44d6-9aef-f7ca67c04840", "name": "lorem ipsum", "uri": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840" }, { "id": "8901870-b526-11e3-a5e2-0800200c9a66", "name": "dolor sit", "uri": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/8901870-b526-11e3-a5e2-0800200c9a66" } ] } ``` {{/ifEqCi}} {{#ifEqCi @key 'POST'}} ```http HTTP/1.1 201 Created Content-Type: application/json; charset=utf-8 ETag: "-32550834" Content-Encoding: gzip Date: Tue, 07 Apr 1980 00:00:00 GMT Connection: keep-alive Transfer-Encoding: chunked Location: /{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840 { "status": "ok" } ``` {{/ifEqCi}} {{/ifnEqCi}} {{/each}} ### Element level access (`/{{extractServiceName ../meta.name}}/{{@key}}/`) {{#each this.objectModel.accessMethods}} #### {{toUpperCase @key }} {{../model.description}} Use a {{methodToText @key }} on `/{{extractServiceName ../../meta.name}}/{{@ ../key}}/` to {{elementLevelAction @key }} [{{@ ../key}}Object](#{{@ ../key}}Object) {{#if this.usesPermissions}} #### Scopes To perform a {{methodToText @key }} on this endpoint, the following scope permissions have to be presented with the `access_token`: {{#each this.usesPermissions }} * {{this}} {{/each}} {{/if}} {{#if this.parameters.properties }} ##### Request parameters The following parameters can be used with the request and subscriptions: | name | type | mandatory | |------------------------------|---------------|-----------| {{#each this.parameters.properties }} | {{strech @key 28}} | {{strech this.type 13}} | {{isMandatory @key ../required 9}} | {{/each}} {{/if}} #### Example {{#ifEqCi @key 'subscribe'}} send to server ```json { "event": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840", "type": "subscribe" } ``` receive a subscription acknowledgement first ```json { "status": "ok", "event": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840", "type": "subscribe" } ``` immediately followed by the initial data message representing current state ```json { "status": "ok", "event": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840", "type": "data", "data": "data": { "id": "3901a278-ba17-44d6-9aef-f7ca67c04840", "name": "lorem ipsum", "uri": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840" } } ``` {{/ifEqCi}} {{#ifnEqCi @key 'SUBSCRIBE'}} ```http {{toUpperCase @key }} /{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840 HTTP/1.1 Host: rsi.local:1337 Connection: keep-alive Accept: application/json Authorization: Bearer Accept-Encoding: gzip,deflate {{#ifEqCi @key 'POST'}} { "rsi": "rockz.." } {{/ifEqCi}} ``` {{#ifEqCi @key 'GET'}} ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 ETag: "-32550834" Content-Encoding: gzip Date: Tue, 07 Apr 1980 00:00:00 GMT Connection: keep-alive Transfer-Encoding: chunked { "status": "ok", "data": { "id": "3901a278-ba17-44d6-9aef-f7ca67c04840", "name": "lorem ipsum", "uri": "/{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840" } } ``` {{/ifEqCi}} {{#ifEqCi @key 'POST'}} ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 ETag: "-32550834" Content-Encoding: gzip Date: Tue, 07 Apr 1980 00:00:00 GMT Connection: keep-alive Transfer-Encoding: chunked { "status": "ok" } ``` {{/ifEqCi}} {{#ifEqCi @key 'DELETE'}} ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 ETag: "-32550834" Content-Encoding: gzip Date: Tue, 07 Apr 1980 00:00:00 GMT Connection: keep-alive Transfer-Encoding: chunked { "status": "ok" } ``` {{/ifEqCi}} {{#ifEqCi @key 'PUT'}} ```http HTTP/1.1 201 Created Vary: Accept-Encoding Content-Type: application/json; charset=utf-8 ETag: "-32550834" Content-Encoding: gzip Date: Tue, 07 Apr 1980 00:00:00 GMT Connection: keep-alive Transfer-Encoding: chunked Location: /{{extractServiceName ../../../meta.name}}/{{@ ../key}}/3901a278-ba17-44d6-9aef-f7ca67c04840 { "status": "ok" } ``` {{/ifEqCi}} {{/ifnEqCi}} {{/each}} {{/each}} # Type Definitions Types - or nested objects - do not have their own `id` or `uri`. Therefore, they can not be adressed separately and are treated as atomic. Types define the nature of an embedded JSON structure in [Objects][(#Objects). {{#each spec.types}} ## {{@key}}Type {{this.description}} ### Attributes | name | description | type | format | unit(s) | value(s) | |------------------------------|------------------------------------------------------------|---------------|---------------|---------------|-----------------------| {{!-- iterate over all attributes of a type --}} {{#each this.attributes}} | {{strech @key 28}} | {{strech this.description 58}} | {{strech this.type 13 }} | {{strech this.format 13}} | {{strech this.unit 13}} | {{getValue this}} | {{/each}} {{/each}} {{/each}}