Provides metadata about protocols, devices, device-types and value-types. Saves data as rdf, publishes changes to amqp and uses permissionsearch for text-search.
Depth
Results may represent a entity and its relations in different depths. Depth -1 means that a entity will be returned with all its relations recursively.
A depth of 1 means that only the entity without its relations will be returned. A depth of 2 means that a entity with only its direct relationships will be returned.
Device-Instance
GET /deviceInstances/:limit/:offset
Lists device instances where the user has reading permissions. Depth -1.
GET /deviceInstances/:limit/:offset/:action
Lists device instances where the user has permissions corresponding to action. Valid actions are read
, write
and execute
. Depth -1.
GET /deviceInstance/:id
Returns device instance if requesting user has reading permission. Depth -1.
POST /deviceInstance
Creates a device instance. Request-Body is a device instance without id and can be prepared with GET /ui/deviceInstance/resourceSkeleton/:deviceTypeId
.
consistent
A device is inconsistent if:
- the url is missing
- the name is missing
- the device-type id does not reference a device-type
- the device-config does not match device-type-config
- the generated device endpoint for a service would collide with a existing endpoint
cqrs
If the device is consistent it will be published to amqp and asynchronously consumed to save the device to the database.
Through this published message other services will also be able to save a representation in its own databases. The permissionsearch service is one example for such services.
endpoints
If the corresponding device-type has a endpoint-format set for a service, it will be used to generate a endpoint pointing to this device and the service.
img
If the ImgUrl field is left empty the img from the associated device type will be used.
uri
A for the protocol unique identifier of the device instance.
POST /deviceInstance/:id
Updates a device instance with similar behavior to the creation.
gateway
If the device-url or a device-tag is changed and the device is assigned to a gateway, the gateways hash will be reset.
This guaranties that the client-connector (gateway) sees the change and has the opportunity to publish its device-information.
DELETE /deviceInstance/:id
removes the device, removes corresponding endpoints, resets hash of assigned gateway. works asynchronous.
GET /ui/deviceInstance/resourceSkeleton/:deviceTypeId
Returns a skeleton of a new device instance which would be of the given device-type. the skeleton can be used for POST /deviceInstance
.
GET /byservice/deviceInstances/:serviceid
Returns device instances that are of the device type that contains the given service and the user has read access to. Depth -1.
GET /byservice/deviceInstances/:serviceid/:action
Returns device instances that are of the device type that contains the given service and the user has the requested access to. Depth -1.
GET /bydevicetype/deviceInstances/:devicetype
Returns device instances that are of the given device type and the user has read access to. Depth -1.
GET /bydevicetype/deviceInstances/:devicetype/:action
Returns device instances that are of the given device type and the user has the requested access to. Depth -1.
GET /url_to_devices/:device_url
Returns a list of objects containing devices and services where the url matches the requested one and the user has read access. Depth -1.
POST /endpoint/in
Returns list of endpoints with matching endpoint string and protocol where the user has execute access and the referenced service is declared as sensor.
POST /endpoint/listen/auth/check/:handler/:endpoint
Checks if user has execute access to all devices referenced by the given endpoint and protocol.
POST /endpoint/out
Returns endpoint of given device and service if user has execute access.
POST /endpoint/generate
Creates new device to be referenced by the given endpoint. If no device type exists that has a matching service a new device type will be created.
If no value type exists to match the given message, a new one will be created.
GET /endpoints/:limit/:offset
Lists all endpoints, if the user has the role "admin"
Gateway
GET /gateways/:limit/:offset
Lists gateways the user has read access to. Depth -1.
GET /gateway/:id
Returns the gateway if the user has read access. Depth -1.
DELETE /gateway/:id
Deletes gateway if user has admin access.
POST /gateway/:id/clear
Removes all associations with devices and sets hash to empty string if the user has write access.
POST /gateway/:id/name/:name
Sets the name of the gateway if the user has write access.
GET /gateway/:id/name
Get the name of the gateway if the user has read access.
POST /gateway/:id/commit
Assigns devices and a hash to the gateway. The commit will fail if a device is already assigned to a different gateway. If this happens you can clear ore delete the other gateway.
Gateway creation and updates are asynchronous, so you may nead to wait a short moment after creation until you can commit.
POST /gateway/:id/provide
Returns a gateway with the given id if the user has execute rights.
If no id is passed or the id is unknown a new gateway will be created and returned.
DeviceType
GET /service/:id
Returns service if user has access rights to related device type.
GET /deviceTypes/:limit/:offset
Lists device types the user has read access to.
GET /maintenance/deviceTypes/:maintenance
Lists device types where the given maintenance flag is set and the user has write access.
GET /maintenance/check/deviceTypes/:maintenance
Checks if any device type has maintenance flag set.
GET /deviceType/:id
Returns device type if user has read access. Depth -1.
GET /deviceType/:id/:depth
Returns devicetype if user has read access, with modifiable depth.
POST /deviceType
Creates asynchronously a new device type.
Consistency
Device type is inconsistent or invalid if:
- the device type has no name
- the device type has no description
- the device type has no assigned vendor
- the device type has no assigned device class
- a config field has no name
- a input/output type assignment has no name
- a input/output type assignment has no assigned known format
- a input/output type assignment has no assigned message segment matching with the protocol
- a input/output type assignment has no assigned valid value type
- a service of the type has no url
- a service of the type has no name
- a service of the type has no description
- a service of the type has no assigned protocol
endpoints
A endpoint references a device-specific instantiation of iot-device-repository.Service.EndpointFormat. The endpoint identifies device-service combinations.
The iot-device-repository.Service.EndpointFormat is a mustache template which may reference device and service uri.
For example /some/path/{{device_uri}}/foo/{{service_uri}}/bar
.
The use of the device uri is highly advised, to ensure that for a devicetype each device has its own service endpoints.
The last example used a structure reminiscent of a http-path, but it can be everything. It is advisable to use one that prevents ambiguous endpoints but it may in fact be somthing like iuhansdcansdc{{device_uri}}asidauisdha
.
If iot-device-repository.Service.EndpointFormat is not empty the iot-repository will create a endpoint for new device instances created of this type.
img
The image link will be used for display in the web-ui. device instances of this type will use this image as default, unless changed.
service.url
A for the device type unique identifier
POST /deviceType/:id
Updates the device type. Endpoints will be updated. device instance images will be updated, if they still use the default image.
POST /import/deviceType
Creates a new device type without consistency check and with user predefined ids.
WARNING: can harm your database.
DELETE /deviceType/:id
Deletes the device type if user has administration access and no device instance with this type exists.
GET /ui/deviceType/allowedvalues
Returns informations about valid values to create new device types and value types.
POST /query/deviceType
Use request-body as partial device type to find matching device type, similar to a mongodb filter.
Returns document containing existence boolean and device type id.
POST /query/service
Use request-body as partial service to find device types with matching services, similar to a mongodb filter.
Returns a list of device type ids.
Intern
this endpoints should be only accessible from internal services, they will not check for the rigths of the requester.
POST /intern/gatewaynames
Maps names to the given gateway ids
POST /intern/device/gatewaynames
Maps names of associated gateways to the given device ids
Other
POST /other/vendor
Creates a new vendor
POST /other/protocol
Creates a new protocol. The protocol url will be used as topic for kafka messages.
POST /other/deviceclass
Creates a new deviceclass
POST /other/valueType
Creates a new valueType.
consistency
a value type is inconsistent if:
- value type has no name
- value type has no description
- value type has no known base type
- value type has not exactly one field if base type is list or map
- value type has not primitive base type and has more than 0 fields
GET /skeleton/:instance_id/:service_id
Returns input/output example for device and service as received by the bpmn-process.
GET /devicetype/skeleton/:type_id/:service_id
like /skeleton/:instance_id/:service_id but with device type.
POST /format/example
Returns message example in the selected format as potentially send to a device.
Search
GET /ui/search/deviceTypes/:query/:limit/:offset
Searches for partial device type matches of name, description etc. (permissionsearch config defines which fields ar searchable). Depth 1.
Searches will be performed by the permissionsearch service, the data will be completed by the rdf triple store.
GET /ui/search/deviceInstances/:query/:limit/:offset
Searches for partial device instance matches of name, description etc. (permissionsearch config defines which fields ar searchable), where the user has read access. Depth -1.
Searches will be performed by the permissionsearch service, the data will be completed by the rdf triple store.
GET /ui/search/deviceInstances/:query/:limit/:offset/:action
Searches for partial device instance matches of name, description etc. (permissionsearch config defines which fields ar searchable), where the user has requested (:action) access. Depth -1.
Searches will be performed by the permissionsearch service, the data will be completed by the rdf triple store.
GET /ui/search/gateways/:query/:limit/:offset
Searches for partial gateway matches of name, description etc. (permissionsearch config defines which fields ar searchable), where the user has read access. Depth -1.
Searches will be performed by the permissionsearch service, the data will be completed by the rdf triple store.
GET /ui/search/valueTypes/:query/:limit/:offset
Searches for value types
GET /ui/search/others/:type/:query/:limit/:offset
Searches for miscellaneous entities. Valid types are vendors
, deviceClasses
and protocols
ValueType
GET /valueTypes/:limit/:offset
Lists value types
GET /valueType/:id
Returns value type
POST /valueType/generate
Generates a value type representing message given by the post body. value type will be returned with the used format, but will not be saved.