{ "swagger": "2.0", "info": { "description": "API definition for CRUD operations on devices. A device is the physical hardware that can be either:

", "version": "1.1.0", "title": "Device Management System", "license": { "name": "Copyright © 2012-26 by Hildebrand Technology Limited" } }, "host": "api.glowmarkt.com", "basePath": "/api/v0-1/", "tags": [ { "name": "DeviceType", "description": "" }, { "name": "Device", "description": "" } ], "schemes": [ "https" ], "paths": { "/devicetype": { "post": { "tags": [ "DeviceType" ], "summary": "Add a new Device Type", "description": "create a new Device Type", "operationId": "deviceType.addDeviceType", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "DeviceType Object", "required": true, "schema": { "$ref": "#/definitions/DeviceTypeReq" } } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/AddDeviceTypeSucess" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/MissingElementsError" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } }, "get": { "tags": [ "DeviceType" ], "summary": "Find all device types", "description": "returns a list of devicetypes", "operationId": "deviceType.findAll", "produces": [ "application/json" ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [] } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/DeviceType" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/devicetype/{id}": { "get": { "tags": [ "DeviceType" ], "summary": "Find Device Type by ID", "description": "Returns a single Device Type", "operationId": "deviceType.findById", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of Device Type to return", "required": true, "type": "string" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/DeviceType" } }, "404": { "description": "Not Found", "schema": { "$ref": "" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device": { "get": { "tags": [ "Device" ], "summary": "Get a user's devices", "description": "Returns an array of the devices that belong to a user.", "operationId": "device.findAll", "parameters": [ { "name": "tags", "in": "query", "required": false, "type": "string", "description": "hardwareId of a device" } ], "produces": [ "application/json" ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/Device" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/missingUserIdError" } }, "404": { "description": "Not Acceptable" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } }, "post": { "tags": [ "Device" ], "summary": "Add a new device", "description": "create a new device", "operationId": "device.addDevice", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "Device Object to add to the device system", "required": true, "schema": { "$ref": "#/definitions/DeviceReq" } } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/AddDeviceSuccess" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/IncorrectElementsError" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device/{id}": { "get": { "tags": [ "Device" ], "summary": "Find device by ID", "description": "Returns a single device", "operationId": "device.findById", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of device to return", "required": true, "type": "string" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Device" } }, "404": { "description": "Not Found", "schema": { "$ref": "" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device/resource/{resourceId}": { "get": { "tags": [ "Device" ], "summary": "Find the device that sources a specified resource.", "description": "Returns a Device, that sources a specified resource.", "operationId": "device.findByResourceId", "produces": [ "application/json" ], "parameters": [ { "name": "resourceId", "in": "path", "description": "Resource ID", "required": true, "type": "string" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Device" } }, "404": { "description": "Not Found", "schema": { "$ref": "" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device/meter-point/{meterPointNumber}/inventory": { "get": { "tags": [ "Device Meter Point DCC inventory" ], "summary": "Get the DCC inventory of a meter point", "description": "Returns the DCC inventory", "operationId": "device.getMeterPointInventory", "produces": [ "application/json" ], "parameters": [ { "name": "meterPointNumber", "in": "path", "description": "Meter Point Number", "required": true, "type": "string" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MeterPointInventoryResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device/smart-meter/{eui}/inventory": { "get": { "tags": [ "Device Meter Point DCC inventory" ], "summary": "Get the DCC inventory of a meter point by providing an EUI.", "description": "Returns the DCC inventory", "operationId": "device.getMeterPointInventoryByEUI", "produces": [ "application/json" ], "parameters": [ { "name": "eui", "in": "path", "description": "EUI", "required": true, "type": "string" } ], "security": [ { "appKeys": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MeterPointInventoryResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device/meter-point/{meterPointNumber}/resources": { "get": { "tags": [ "Device Meter Point DCC inventory" ], "summary": "Get the resources associated to a meter point", "description": "Returns the resources that are associated to a meter point", "operationId": "device.getMeterPointResources", "produces": [ "application/json" ], "parameters": [ { "name": "meterPointNumber", "in": "path", "description": "Meter Point Number", "required": true, "type": "string" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MeterPointResourceResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device/{id}/status": { "get": { "tags": [ "Device" ], "summary": "This call can be used to see whether a gateway device is sending packets to the Glow Platform (i.e. via WiFi).", "operationId": "device.getStatusbyDeviceId", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of device to return", "required": true, "type": "string" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "found": { "type": "boolean", "example": true }, "deviceId": { "type": "string", "example": "55c883e0-701e-4810-acf1-e827dbd83fb0" }, "hardwareId": { "type": "string", "example": "968YHFEKLQ" }, "value": { "type": "number", "example": 1517317927 } } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/IncorrectElementsError" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/device/status": { "get": { "tags": [ "Device" ], "summary": "This call can be used to see whether a gateway device is sending packets to the Glow Platform (i.e. via WiFi).", "operationId": "device.getStatusbyHardwareId", "produces": [ "application/json" ], "parameters": [ { "name": "tags", "in": "query", "required": true, "type": "string", "description": "the HardwareId of the device" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "found": { "type": "boolean", "example": true }, "deviceId": { "type": "string", "example": "55c883e0-701e-4810-acf1-e827dbd83fb0" }, "hardwareId": { "type": "string", "example": "968YHFEKLQ" }, "value": { "type": "number", "example": 1517317927 } } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/IncorrectElementsError" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ServerError" } } } } }, "/discover/{hardwareId}": { "get": { "tags": [ "discover" ], "summary": "Find device by ID", "description": "Returns the devices and if they do not exist the assets and product types", "operationId": "discoverDevicesAssets", "produces": [ "application/json" ], "parameters": [ { "name": "hardwareId", "in": "path", "description": "A hardware identifier of a Device. For a network device, we typically use the MAC address.", "required": true, "type": "string" } ], "security": [ { "userToken": [], "applicationId": [] }, { "appKeys": [], "userId": [] } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "" } }, "404": { "description": "Not Found", "schema": { "$ref": "" } }, "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": "userId", "in": "header" } }, "definitions": { "MeterPointInventory": { "type": "object", "properties": { "DateCommissioned": { "type": "string", "example": "2022-02-02T00:00:00.000Z" }, "DeviceFirmwareVersion": { "type": "string", "example": "111" }, "DeviceManufacturer": { "type": "string", "example": "METER_MANUFACTURER" }, "DeviceModel": { "type": "string", "example": 333333 }, "DeviceType": { "type": "string", "example": "CHF" }, "DeviceStatus": { "type": "string", "example": "Commissioned" }, "EUI": { "type": "string", "example": "AB123456789012" }, "ImportMPxN": { "type": "string", "example": 123456789012 }, "SmetsVersion": { "type": "string", "example": 2 } } }, "MeterPointInventoryResponse": { "type": "object", "properties": { "valid": { "type": "boolean" }, "inventory": { "type": "array", "items": { "$ref": "#/definitions/MeterPointInventory" } } } }, "MeterPointResourceResponse": { "type": "object", "properties": { "valid": { "type": "boolean", "example": true }, "mpxn": { "type": "string", "example": 123456789012 }, "resources": { "type": "array", "items": { "$ref": "#/definitions/ResourceListingWithClassifier" } } } }, "ProtocolResourceType": { "type": "object", "properties": { "protocolId": { "type": "string" }, "resourceTypeId": { "type": "string" } }, "required": [ "protocolId", "resourceTypeId" ] }, "ProtocolResourceTypeResource": { "type": "object", "properties": { "protocolId": { "type": "string" }, "resourceTypeId": { "type": "string" }, "resourceId": { "type": "string" } }, "required": [ "protocolId", "resourceTypeId", "resourceId" ] }, "DeviceTypeReq": { "type": "object", "properties": { "description": { "type": "string" }, "protocol": { "type": "object", "properties": { "sensors": { "type": "array", "items": { "$ref": "#/definitions/ProtocolResourceType" } }, "protocol": { "type": "string" } }, "required": [ "protocol", "sensors" ] } } }, "DeviceReq": { "type": "object", "properties": { "deviceTypeId": { "type": "string" }, "hardwareId": { "type": "string" }, "hardwareIds": { "type": "object" } }, "required": [ "deviceTypeId", "hardwareId", "hardwareIds" ] }, "ParentHardwareIds": { "type": "string", "example": "KO17321203" }, "DeviceType": { "type": "object", "properties": { "deviceTypeId": { "type": "string" }, "description": { "type": "string" }, "protocol": { "type": "object", "properties": { "sensors": { "type": "array", "items": { "$ref": "#/definitions/ProtocolResourceTypeResource" } }, "protocol": { "type": "string" } }, "required": [ "protocol", "sensors" ] } } }, "Device": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "55c883e0-701e-4810-acf1-e827dbd83fb0" }, "deviceTypeId": { "type": "string" }, "ownerId": { "type": "string" }, "description": { "type": "string" }, "hardwareId": { "type": "string", "example": "60001" }, "hardwareIds": { "type": "object", "example": { "sid": "60001" } }, "parentHardwareId": { "type": "array", "items": { "$ref": "#/definitions/ParentHardwareIds" } }, "protocol": { "type": "object", "properties": { "sensors": { "type": "array", "items": { "$ref": "#/definitions/ProtocolResourceTypeResource" } }, "protocol": { "type": "string" } }, "required": [ "protocol", "sensors" ] } }, "required": [ "ownerId", "hardwareId" ] }, "ResourceListingWithClassifier": { "type": "object", "properties": { "resourceId": { "type": "string", "example": "8f2a0722-3b59-47a6-a115-d43fcc0c5d1c" }, "resourceTypeId": { "type": "string", "example": "f8e6fb07-6307-4e0e-8a17-4b94bc7249c2" }, "classifier": { "type": "string", "example": "electricity.consumption" } }, "xml": { "name": "ResourceListingWithClassifier" } }, "ServerError": { "type": "object", "properties": { "error": { "type": "string", "example": "An error has occurred" } }, "xml": { "name": "AddResourceError" } }, "AddDeviceTypeSucess": { "type": "object", "properties": { "status": { "type": "string", "example": "OK" }, "deviceTypeId": { "type": "string", "example": "a0872822-c10c-4a90-bf8a-17310ffe10af" } } }, "missingUserIdError": { "type": "object", "properties": { "error": { "type": "string", "example": "missing elements -userId" } } }, "AddDeviceSuccess": { "type": "object", "properties": { "status": { "type": "string", "example": "OK" }, "valid": { "type": "boolean" }, "deviceId": { "type": "string", "example": "d3vb0129-8c95-43f3-bde2-744007221oli" } } }, "IncorrectElementsError": { "type": "object", "properties": { "error": { "type": "string", "example": "incorrect elements" } } }, "MissingElementsError": { "type": "object", "properties": { "error": { "type": "string", "example": "missing elements" } } } } }