{"swaggerDoc":{"swagger":"2.0","info":{"description":"API definition for CRUD operations on Virtual Entities. In the Glow Platform a Virtual Entity, is the virtual representation of a physical “thing” that is comprised of metadata and a collection of resources that define and describe it. An example of a Virtual Entity is a home with electricity energy readings sourced from a smart meter.","version":"1.3.0","title":"Virtual Entity System","license":{"name":"Copyright © 2012-24 by Hildebrand Technology Limited"}},"host":"api.glowmarkt.com","basePath":"/api/v0-1/","tags":[{"name":"Virtual Entity Type","description":"Entity that belongs and is managed by an application and contains the definition and combination of the Resource Types that are required to create a Virtual Entity."},{"name":"Virtual Entity","description":"A Virtual Entity is an instance of the Virtual Entity Type and is tied to an owner as well as an applicationId. In order to create a Virtual Entity a user must have all the required resources."},{"name":"Virtual Entity's Metadata","description":"A Virtual Entity's metadata can be used to save information that will facilitate the virtual representation of the entity. This is typically attribute data that does not change in time."},{"name":"Virtual Entity Statistics","description":"APIs that return an overview of the Virtual Entities an application has (administrative API)."}],"schemes":["https"],"paths":{"/vetype":{"post":{"tags":["Virtual Entity Type"],"summary":"Add a new Virtual Entity Type","description":"Create a new Virtual Entity Type","operationId":"veType.addVeType","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"body","description":"Virtual Entity Type payload","required":true,"schema":{"$ref":"#/definitions/newVeTypeReq"}}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/newVeTypeRes"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}},"get":{"tags":["Virtual Entity Type"],"summary":"Find all Virtual Entity Types","description":"Returns a list of the application's Virtual Entity Types.","operationId":"veType.findAll","produces":["application/json"],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ListOfVeType"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}},"/vetype/{id}":{"get":{"tags":["Virtual Entity Type"],"summary":"Find Virtual Entity Type by ID","description":"Returns a single Virtual Entity Type","operationId":"veType.findById","produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity Type ID","required":true,"type":"string"}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/VeType"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"404":{"description":"Not Found","schema":{"type":"string","example":null}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}},"put":{"tags":["Virtual Entity Type"],"summary":"Update a Virtual Entity Type","description":"Update Virtual Entity Type. Please note that only specific properties of the Virtual Entity Type can be updated, such as the name and the description.","operationId":"veType.updateVeType","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity Type ID","required":true,"type":"string"},{"in":"body","name":"body","description":"Virtual Entity Type to be updated.","required":true,"schema":{"$ref":"#/definitions/updateVeTypeReq"}}],"security":[{"appKeys":[]}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/newVeTypeRes"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}},"/vetype/{id}/resources":{"get":{"tags":["Virtual Entity Type"],"summary":"Find all resources that belong to a user that satisfy the Resource Types in the Virtual Entity Type definition.","description":"Returns the resources of a user that could potentially be used to create a Virtual Entity of the specified Virtual Entity Type","operationId":"veType.findResourcesOfVeType","produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity Type ID","required":true,"type":"string"}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[],"userId":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/VeTypeResources"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}},"/virtualentity":{"post":{"tags":["Virtual Entity"],"summary":"Add a new Virtual Entity","description":"create a new Virtual Entity","operationId":"virtualentity.addVirtualEntity","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"body","description":"Virtual Entity object to add to the resource system","required":true,"schema":{"$ref":"#/definitions/VEReq"}}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[],"userId":[]}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/AddVeSucess"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}},"get":{"tags":["Virtual Entity"],"summary":"Find all Virtual Entities","description":"Returns a list of Virtual Entities that belong to an application (and a user if applicable)","operationId":"virtualentity.findAll","produces":["application/json"],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ListOfVe"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}},"/virtualentity/{id}":{"get":{"tags":["Virtual Entity"],"summary":"Find Virtual Entity by ID","description":"Returns a single Virtual Entity","operationId":"virtualentity.findById","produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity ID","required":true,"type":"string"}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Ve"}},"404":{"description":"Not Found","schema":{"type":"string","example":null}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}},"put":{"tags":["Virtual Entity"],"summary":"Update a Virtual Entity","description":"Please note that only specific properties of the Virtual Entity can be updated. These includes the following: name, description, location, city, country, postalCodem geoCoordinates, openStreetMapsRef, timeZone.","operationId":"virtualentity.updateVirtualEntity","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity ID","required":true,"type":"string"},{"in":"body","name":"body","description":"The data that is to be updated on a Virtual Entity object.","required":true,"schema":{"$ref":"#/definitions/VEUpdateReq"}}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[],"userId":[]}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/AddVeSucess"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}},"delete":{"tags":["Virtual Entity"],"summary":"Delete a Virtual Entity","description":"Delete a single Virtual Entity","operationId":"virtualentity.deactivateVirtualEntity","produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity ID","required":true,"type":"string"}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Vedeactive"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}},"/virtualentity/{id}/resources":{"get":{"tags":["Virtual Entity"],"summary":"Find the resources of that belong to Virtual Entity with ID","description":"Returns a single Virtual Entity with a resource list of the full resource docs","operationId":"virtualentity.findResourcesbyVeId","produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity ID","required":true,"type":"string"}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/VeWithFullResources"}},"404":{"description":"Not Found","schema":{"type":"string","example":null}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}},"/virtualentity/{id}/attribute":{"get":{"tags":["Virtual Entity's Metadata"],"summary":"Find a Virtual Entity's metadata by ID","description":"Returns all the metadata of a Virtual Entity","operationId":"virtualentity.getAttributes","produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity ID","required":true,"type":"string"}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/GetAtrributesRes"}},"401":{"description":"Unauthorised","schema":{"$ref":"#/definitions/AccessDeniedError"}},"404":{"description":"Not Found","schema":{"type":"string","example":null}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}},"post":{"tags":["Virtual Entity's Metadata"],"summary":"Add/Update a Virtual Entity's metadata","description":"Add/Update a Virtual Entity's metadata. Whichever fields are included in body of call, will be updated","operationId":"virtualentity.add-updateAttributes","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity ID","required":true,"type":"string"},{"in":"body","name":"body","description":"Virtual Entity metadata to be added or modified,","required":true,"schema":{"$ref":"#/definitions/VEReqUpdateAttributes"}}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[],"userId":[]}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/GetAtrributesRes"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}},"delete":{"tags":["Virtual Entity's Metadata"],"summary":"delete metadata from the Virtual Entity","description":"Pieces of metadata provided in the body will be deleted from the Virtual Entityl","operationId":"virtualentity.deleteAttributes","produces":["application/json"],"parameters":[{"name":"id","in":"path","description":"Virtual Entity ID","required":true,"type":"string"},{"in":"body","name":"body","description":"Virtual Entity metadata to be deleted","required":true,"schema":{"$ref":"#/definitions/VEReqDeleteAttributes"}}],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/VEResDeletedAttributes"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}},"/vesys/appstats":{"get":{"tags":["Virtual Entity Statistics"],"summary":"find statistics on the number of Virtual Entities per application","description":"Returns a single statistics entity","operationId":"stats.getApplicationVeStats","produces":["application/json"],"security":[{"userToken":[],"applicationId":[]},{"appKeys":[]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/VeStats"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/reqError"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/ServerError"}}}}}},"securityDefinitions":{"orgAppKeys":{"type":"basic"},"appKeys":{"type":"basic"},"devUserToken":{"type":"apiKey","name":"token","in":"header"},"userToken":{"type":"apiKey","name":"token","in":"header"},"applicationId":{"type":"apiKey","name":"applicationId","in":"header"},"userId":{"type":"apiKey","name":"applicationId","in":"header"}},"definitions":{"newVeTypeReq":{"type":"object","properties":{"name":{"type":"string","example":"Smart Home"},"description":{"type":"string","example":"Smart home, with electricity and gas utilities"},"resources":{"type":"array","items":{"type":"object","properties":{"resourceTypeId":{"type":"string","example":"f8e6fb07-6307-4e0e-8a17-4b94bc7249c2"},"required":{"type":"boolean"}}}}}},"updateVeTypeReq":{"type":"object","properties":{"name":{"type":"string","example":"Smart Home"},"description":{"type":"string","example":"Smart home, with electricity and gas utilities"}}},"reqError":{"type":"object","properties":{"error":{"type":"string","example":"missing elements"}}},"newVeTypeRes":{"type":"object","properties":{"status":{"type":"string","example":"OK"},"veTypeId":{"type":"string","example":"b82d4f8b-a097-4b96-acbb-81d891489441"}}},"VeType":{"type":"object","properties":{"veTypeId":{"type":"string","example":"cc90b599-2705-4b13-98d4-3306f81169cf"},"name":{"type":"string","example":"home Virtual Entity"},"description":{"type":"string","description":"home with two types of resources"},"applicationId":{"type":"string","example":"a0cf21a2-51f6-4df2-9214-0bc762bcee09"},"active":{"type":"boolean"},"resources":{"type":"array","items":{"type":"object","properties":{"resourceTypeId":{"type":"string","example":"f8e6fb07-6307-4e0e-8a17-4b94bc7249c2"},"required":{"type":"boolean"}}}}}},"VeTypeResources":{"type":"object","properties":{"veTypeId":{"type":"string","example":"cc90b599-2705-4b13-98d4-3306f81169cf"},"ownerId":{"type":"string","example":"f78a3812-d4fc-4b00-99c5-20fd581721a6"},"applicationId":{"type":"string","example":"a0cf21a2-51f6-4df2-9214-0bc762bcee09"},"resources":{"type":"array","items":{"$ref":"#/definitions/ResourceTypeAvailableResources"}},"selectionNeeded":{"type":"boolean"}}},"ResourceTypeAvailableResources":{"type":"object","properties":{"resourceTypeId":{"type":"string","example":"f8e6fb07-6307-4e0e-8a17-4b94bc7249c2"},"required":{"type":"boolean"},"options":{"type":"array","items":{"$ref":"#/definitions/Resource"}}}},"Resource":{"type":"object","properties":{"resourceId":{"type":"string","example":"8f2a0722-3b59-47a6-a115-d43fcc0c5d1c"},"resourceTypeId":{"type":"string","example":"f8e6fb07-6307-4e0e-8a17-4b94bc7249c2"},"name":{"type":"string","example":"solar updated access test"},"description":{"type":"string","example":"solar generation of hid"},"dataSourceUnitInfo":{"type":"object","properties":{"shid":{"type":"string","example":"f3204e8e5b1a40a39396a15f919f88a5"}}},"ownerId":{"type":"string","example":"f78a3812-d4fc-4b00-99c5-20fd581721a6"},"label":{"type":"string","example":"solar resourceType test"},"dataSourceResourceTypeInfo":{"type":"object","properties":{"type":{"type":"string","example":"PWER_GAC"}}},"dataSourceType":{"type":"string","example":"EHSOLAPI"},"active":{"type":"boolean"}}},"VEReq":{"type":"object","properties":{"veTypeId":{"type":"string","example":"cc90b599-2705-4b13-98d4-3306f81169cf"},"name":{"type":"string","example":"My special name"},"resources":{"type":"array","items":{"type":"object","properties":{"resourceId":{"type":"string","example":"319aef2c-45fe-4027-9c2a-cf1cb8f8c0f1"}}}}}},"VEUpdateReq":{"type":"object","properties":{"name":{"type":"string","example":"A new name"},"description":{"type":"string","example":"This virtual entity represents my home."}}},"VEReqUpdateAttributes":{"type":"object","description":"Anything can be added in a ve's metadata","properties":{"rooms":{"type":"array","items":{"type":"string","example":"living room"}},"area":{"type":"object","properties":{"units":{"type":"string","example":"sqm"},"measurement":{"type":"string","example":100}}}}},"VEReqDeleteAttributes":{"type":"object","description":"Insert the attributes you would like to delete under the field removeAttributes","properties":{"removeAttributes":{"type":"object","properties":{"area":{"type":"object","properties":{"units":{"type":"string","example":"sqm"},"measurement":{"type":"string","example":100}}}}}},"required":["removeAttributes"]},"VEResDeletedAttributes":{"type":"object","properties":{"status":{"type":"string","example":"OK"},"veId":{"type":"string","example":"dc9069a7-7695-43fd-8f27-16b1c94213da"},"rooms":{"type":"array","items":{"type":"string","example":"living room"}}},"required":["veId","status"]},"Ve":{"type":"object","properties":{"veId":{"type":"string","example":"dc9069a7-7695-43fd-8f27-16b1c94213da"},"veTypeId":{"type":"string","example":"cc90b599-2705-4b13-98d4-3306f81169cf"},"name":{"type":"string","example":"veTry status"},"ownerId":{"type":"string","example":"f78a3812-d4fc-4b00-99c5-20fd581721a6"},"applicationId":{"type":"string","example":"a0cf21a2-51f6-4df2-9214-0bc762bcee09"},"active":{"type":"boolean"},"resources":{"type":"array","items":{"type":"object","properties":{"resourceId":{"type":"string","example":"319aef2c-45fe-4027-9c2a-cf1cb8f8c0f1"},"resourceTypeId":{"type":"string","example":"f8e6fb07-6307-4e0e-8a17-4b94bc7249c2"}}}},"attribute":{"type":"object","description":"Anything can be saved under this field","properties":{"rooms":{"type":"array","items":{"type":"string","example":"living room"}},"area":{"type":"object","properties":{"units":{"type":"string","example":"sqm"},"measurement":{"type":"string","example":100}}}}}}},"VeWithFullResources":{"type":"object","properties":{"veId":{"type":"string","example":"dc9069a7-7695-43fd-8f27-16b1c94213da"},"veTypeId":{"type":"string","example":"cc90b599-2705-4b13-98d4-3306f81169cf"},"name":{"type":"string","example":"veTry status"},"ownerId":{"type":"string","example":"f78a3812-d4fc-4b00-99c5-20fd581721a6"},"applicationId":{"type":"string","example":"a0cf21a2-51f6-4df2-9214-0bc762bcee09"},"active":{"type":"boolean"},"resources":{"type":"array","items":{"$ref":"#/definitions/Resource"}},"attribute":{"type":"object","description":"Anything can be saved under this field","properties":{"rooms":{"type":"array","items":{"type":"string","example":"living room"}},"area":{"type":"object","properties":{"units":{"type":"string","example":"sqm"},"measurement":{"type":"string","example":100}}}}}}},"GetAtrributesRes":{"type":"object","properties":{"veId":{"type":"string"},"attribute":{"type":"object","description":"Anything can be saved under this field","properties":{"rooms":{"type":"array","items":{"type":"string","example":"living room"}},"area":{"type":"object","properties":{"units":{"type":"string","example":"sqm"},"measurement":{"type":"string","example":100}}}}}}},"Vedeactive":{"type":"object","properties":{"veId":{"type":"string","example":"dc9069a7-7695-43fd-8f27-16b1c94213da"},"veTypeId":{"type":"string","example":"cc90b599-2705-4b13-98d4-3306f81169cf"},"name":{"type":"string","example":"veTry status"},"ownerId":{"type":"string","example":"f78a3812-d4fc-4b00-99c5-20fd581721a6"},"applicationId":{"type":"string","example":"a0cf21a2-51f6-4df2-9214-0bc762bcee09"},"active":{"type":"boolean","default":false},"resources":{"type":"array","items":{"type":"object","properties":{"resourceId":{"type":"string","example":"319aef2c-45fe-4027-9c2a-cf1cb8f8c0f1"},"resourceTypeId":{"type":"string","example":"f8e6fb07-6307-4e0e-8a17-4b94bc7249c2"}}}}}},"ListOfVeType":{"type":"array","items":{"$ref":"#/definitions/VeType"}},"ListOfVe":{"type":"array","items":{"$ref":"#/definitions/Ve"}},"ServerError":{"type":"object","properties":{"error":{"type":"string","example":"An error has occurred"}},"xml":{"name":"AddResourceError"}},"AddVeSucess":{"type":"object","properties":{"status":{"type":"string","example":"OK"},"veId":{"type":"string","example":"e10591ec-4557-4ac7-90d4-a09654aeb5de"}}},"VeStats":{"type":"object","properties":{"applicationId":{"type":"string","example":"a0cf21a2-51f6-4df2-9214-0bc762bcee09"},"totalVirtualEntities":{"type":"integer","example":3},"newVirtualEntities":{"type":"object","properties":{"P1D":{"type":"integer","example":0},"P1W":{"type":"integer","example":1},"P1M":{"type":"integer","example":3}}}}},"AccessDeniedError":{"type":"object","properties":{"error":{"type":"string","example":"Access denied"}}}}},"customOptions":{}}