Transcription
WAGO Cloud - REST-API DocumentationWAGO Cloud - REST-API DocumentationV ers ion: 2. 02021-12-14File name: WAGO Cloud - RE ST-API D ocumentation.docx
WAGO Cloud - REST-API DocumentationTable of contents1 Overvi ew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Supported Components by REST -API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.2 D ef init ion of Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2.3 S upported Operations by RES T-AP I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44453 RES T-API Usage via S wagger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.2 RES T-AP I K ey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.2. 1 Create an AP I Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.3 A ut horization via S wagger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.4 RES T-AP I Op eratio ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 RES T-API S cenarios vi a HTTP requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.1 A ut horization via RES T-AP I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.2 Get S ubscription and Workspac e Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.3 Creat e a D evice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.4 Get all Commands Support ed f or a Devic e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.5 S end a Command to the Dev ice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.6 Get the Wo rkspace St ruct ure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.7 Get Telemet ry Dat a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Publi c E vent Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.1 S upported Public Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.2 S ubscrib e for a Public Event - POS T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3 S equenc e of Events: Sync hrono us Handshake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285.4 List all Public Event Subsc riptions - GE T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295.5 Unsubscribe f rom a P ublic Event - DELE TE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305.6 Receiv e Scheduled CSV Export Ev ents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305.7 Receiv e Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315.8 Receiv e Devic e St ate Ev ents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315.9 Receiv e Telemetry D ata Ev ents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Asynchronous Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356.1 How to use it . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356.2 D evice Command Response St ates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386.3 Change Timeout Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396.4 Retry P att ern f or WA GO Cloud Devic e Command S erv ice . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
WAGO Cloud - REST-API Documentation1 OverviewB es ides managing t he d evices in t he WA GO Cloud Web -Portal, it is also possible t omanage t he WA GO Cloud and t he data v ia t he REST-API. The RE ST-API p rovidest he f ollowing use c ases andf unctions:Us e c as es of t he RE ST-API: S c riptinge. g . automatic d evicereg istration Cus t om applications D at a access onhis t orical dataRE S T-A PI Functions: D ev ice management andac c ess to d evice d ata S ub scription andwo rk space management A larm conf iguration andac c ess to alarm d ataThis d ocument d escribes t he architecture f rom t he new v ersion of t he RE ST-API andg iv es s ome b asic example how t o register a d evice and receive d ata f rom t he d evice.If y o u are wo rking with an o lder v ersion of t he RE ST A PI v 1 (deprecated) o r v 2(d ep recated), p lease us e t he REST-API d ocumentation f rom 2018-10-01, V ersion 2.2.
WAGO Cloud - REST-API Documentation2 Supported Components by REST-API2.1 OverviewThe f ollowing picture s hows t he components, which are s upported by t he REST -API.E ac h t erm used in t he picture is d escribed in t he t able f ollowed by t he picture.Frame/CoreDevicesTelemetry Data Subscription info Device management Get raw data Workspace info Command management Get aggregated data Workspace/folder/devicestructure management Collection info Tag info Event managementAlarms Manage alarmconfigurations Manage triggered alarms Alarm statusFig u re 1 : S u p p o rt e d co mp o n e n t s2.2 Definition of T ermsTermDefi nitionFram e/CoreThe g eneral f unctionality in t he WA GO Cloud is c lusteredin t he f rame/core c omponent, e.g. s ubscription andwo rk space management.The RE S T-API allows t o get s ubscription and workspaceinf ormation. The management of t he workspace s tructureis als o possible. It is also possible t o c reate as ub scription t hat inf orms about an event by s endingc allbacks t o a s pecif ied c lient .Devi ceD ev ices c an b e c reated in t he WAGO Cloud. D evices,t o gether with f olders, are contained in t he wo rkspaces t ructure. D ata c an b e s ent f rom t he p hysical d evice. Thes ent d ata us e c ollections and t ags f or t he t ransmission ofd ev ice d ata. Commands c an b e ex ecuted o n t he device.The RE S T-API allows t o get d evice inf o and c reate o rd elete devices. Commands c an b e read and t riggered ont he d evice. Co llections and t ags c an be also c reated,up d ated and d eleted. Conf iguration of d evice is alsop o ssible. D eveloper c an use A PI t o conf igure d eviceins t ead of s ending a t ag conf iguration message.
WAGO Cloud - REST-API DocumentationTermDefi nitionTel emetry dataThe p hysical device c an s end t elemetry data to t he c loud.The t elemetry data c an be v isualized in t he WAGO Cloud,e. g . in a d ashboard o r in a t rend.The RE S T-API allows t o export t he raw d ata f rom t hed ev ice and t he aggregat ed data f rom t he device. You c anus e t he d ata in any other 3 r d p arty t ool.Al arm sThe WA GO Cloud c ontains an alarm management app.A larm conf iguration c an be c reated with s ever al alarmrules . While s ending t elemet ry d at a f rom devices, t healarm c onf igurations will b e c hecked and if a rule is metan alarm in t he WA GO Cloud will b e c reated.The RE S T-API s upports t he management of t he alarmc o nf igurations and t he management of t rig gered alarms.The ac c ess t o t he WA GO Cloud c omponents is always res tricted b y t he WAGO Cloudus er management. A n A PI k ey (p rimary o r s econdary) is necessary A ccess t o WAGOClo ud is always v ia a us er.2.3 Supported Operations by REST -APIApp / Category Method / OperationDescri ptionCore 1. 0 S ubscriptionsGE T/ ap i/core/subscriptionsGet s all s ubscriptioninf ormation t he us er doeshav e ac cess t o.GE T/ ap i/core/subscriptions/{id}Get s t he s ubscriptioninf ormation f or t hes p ecified id.GE T/ ap i/core/subscriptions/{id}/ wo rkspacesGet s a list of allwo rk spaces f or t hes ub scription with t he givenid .P UT/ ap i/core/subscriptions/{id}/ appsReg ister or updat e t hereg istration of an ex istingap p lication.GE T/ ap i/core/subscriptions/{id}/ appsGet s t he list of allreg istered apps t hat werereg istered f or t hes ub scription with t he givenid .D E LETE/ ap i/core/subscriptions/{id}/ apps/ {name}D eregist ers t he app witht he g iven name f rom t hes ub scription with t he givenid .
WAGO Cloud - REST-API DocumentationApp / Category Method / OperationDescri ptionCore 1. 0 WorkspacesGE T/ ap i/core/workspaces/{id}/structureGet s t he wo rkspaces t ructure f or t hewo rk space wit h t he givenid .P OS T/ ap i/core/workspaces/{id}/structureCreat es a f older in t hewo rk space s tructure.P UT/ ap i/core/workspaces/{id}/structureUp d ates a node in t hewo rk space s tructure.GE T/ ap i/core/workspaces/{id}/structure/ s earchS earc hes f or o bjects(d ev ices/folder) wit hin t hewo rk space wit h t he givenid .GE T/ ap i/core/workspaces/{id}/structure/ {no deId}S earc hes f or t he s tructureno d e wit h t he g iven nodeid in t he wo rkspace witht he g iven wo rkspace id.GE T/ ap i/core/workspaces/{id}/structure/ {no deId}/additional -propertiesGet s t he addit ionalp ro perties f or a s p ecif icno d e f older o r d evice,c o llection o r t ag.P UT/ ap i/core/workspaces/{id}/structure/ {no deId}/additional-propertiesCreat es o r updates t head d itional properties f or as p ecific node f older o rd ev ice, c ollection o r t ag.GE T/ ap i/core/workspaces/{id}/strcture/ {no deId}/aggregated-tagsGet s t he c onfigureds t ructural t ag aggregatesf o r a f older, d evice o rwo rk spaceD E LETE/ ap i/core/workspaces/{f olderId}/ f olderD eletes t he s pecif iedf o lder and its s ub-f olders.D E LETE/ ap i/core/workspaces/{id}/structure/ {no deId}/additional -properties/ {p ropertyName}D eletes t he additionalp ro perties f or a s p ecif icno d e f older o r d evice,c o llection o r t ag with t heg iv en p roperty name.GE T/ ap i/core/workspaces/{id}/featurep ermissionsGet s t he f eaturep ermissions t he c allingus er d oes have within t hewo rk space wit h t he givenid entif ier.
WAGO Cloud - REST-API DocumentationApp / Category Method / OperationDescri ptionCore 1. 0 E ventsP OS T/ ap i/core/eventsubscriptionsCreat es a s ubscript iont hat inf orms about anev ent by s endingc allbacks t o a s pecif iedc lient.GE T/ ap i/core/eventsubscriptionsLis t s all c urrently ac tiveev ent s ubscriptions.D E LETE/ ap i/core/eventsubscriptions/ {id}D eletes a p reviouslyc reat ed ev ents ub scription.GE T/ ap i/deviceapp/devicesGet s all d evices f or t heg iv en workspace t he userd o es have ac cess t o.P OS T/ ap i/deviceapp/devicesCreat es a d evice in t hewo rk space wit h t he givenid .GE T/ ap i/deviceapp/devices/{id}Ret urns t he d evice wit ht he g iven id.P UT/ ap i/deviceapp/devices/{id}Up d ates p roperties of ad ev ice with t he g iven id.D E LETE/ ap i/deviceapp/devices/{id}D eletes t he d evice withg iv en id.GE T/ ap i/deviceapp/devices/{id}/ c o mmandsGet s all c ommandss up ported b y t he d evicewit h t he g iven id.P OS T/ ap i/deviceapp/devices/{id}/ c o mmands/{command}S end s t he specifiedc o mmand request t o t hed ev ice with t he g iven id.GE TGet s t he s pecif iedc o mmand responseas y nchronously with t heg iv en c ommand responseidDevi ce 1. 0 –Devi ces/ ap i/deviceapp/devices/{deviceId}/ c o mmandResponse/ {c ommandResponseId}P OS T/ ap i/deviceapp/devices/{deviceId}/ c o mmandsAsync/{command}GE T/ ap i/deviceapp/devices/{id}/ c o llectionsS end s t he specifiedc o mmand requestas y nchronously to t hed ev ice with t he g ivenp arameters.Get s all c ollections f or t hed ev ice with t he g iven id.
WAGO Cloud - REST-API DocumentationApp / Category Method / OperationDevi ce 2. 0 –Devi cesTel emetry 1.0Tel emetryDataDescri ptionP UT/ ap i/deviceapp/devices/{id}/ c o llectionsCreat es/Updates t hec o llections f or t he d evicewit h t he g iven id.GE T/ ap i/deviceapp/devices/{id}/ c o llections/{key}/t agsGet s t he t ags f or t hes p ecified c ollection f or t hed ev ice with t he g iven id.P UT/ ap i/deviceapp/devices/{id}/ c o llections/{key}/t agsCreat es/Updates t he t agsf o r t he device collection.P OS T/ api/deviceapp/devices/{id}/ c o mmands/{command}S end s t he specifiedc o mmand request t o t hed ev ice with t he g iven id.GE T/ api/deviceapp/devices/ {d eviceId}/commandResponse/ {c ommandResponseId}Get s t he s pecif iedc o mmand responseas y nchronously with t heg iv en c ommand responseidP OS T/ api/deviceapp/devices/ {d eviceId}/commandsAsync/ {c ommand}S end s t he specifiedc o mmand requestas y nchronously to t hed ev ice with t he g ivenp arameters.P OS T/ ap i/telemetry/telemetrydata/rawGet s t he raw d ata v aluesf o r all g iven t agd es criptions.P OS T/ ap i/telemetry/telemetrydata/ ag gregates/datapointsGet s t he aggregated d atav alues f or t he given t agd es criptions. The res ultwill b e p acked into t heg iv en number of ev ens ized d atapoints.P OS T/ ap i/telemetry/telemetrydata/ ag gregates/timeintervalGet s t he aggregated d atav alues f or t he given t agd es criptions. The res ultwill b e aggregat ed intot ime b uckets of t he givent ime interval.P OS T/ ap i/telemetry/telemetrydata/ ag gregates/timewindowGet ag gregates withwind owing.
WAGO Cloud - REST-API DocumentationApp / Category Method / OperationAl arm 1.0 Al armConfi gurationsAl arm 1.0 –Al arm sDescri ptionP OS T/ ap i/telemetry/telemetrydata/latestGet s f or g iven t ags t helat es t t elemetry datav alues.P OS T/ ap i/telemetry/telemetrydata/atGet s t he d at a v alues f ort he g iven t ags at t hes p ecified point in t ime.P OS T/ ap i/telemetry/telemetrydata/ s t ructuralaggregates/latestGet s s tructuralag g regation b ased o n t helas t v alues.P OS T/ ap i/telemetry/telemetrydata/ s t ructuralaggregates/timewindowGet s t ructural aggregateswit h windowingGE T/ ap i/alarmapp/alarmconfigurationsGet s t he ex isting alarmc o nf igurations f or t heg iv en workspace or deviceres p ectively.P OS T/ ap i/alarmapp/alarmconfigurations/ p lcStatusBasedCreat e a p lc s tatus b asedalarm c onf iguration.P UT/ ap i/alarmapp/alarmconfigurations/ p lcStatusBased/{id}Up d ates a p lc s tatusb as ed alarm conf iguration.P OS T/ ap i/alarmapp/alarmconfigurations/ v alueBasedCreat e a v alue b asedalarm c onf iguration.P UT/ ap i/alarmapp/alarmconfigurations/ v alueBased/{id}Up d ates a v alue basedalarm c onf iguration.P OS T/ ap i/alarmapp/alarmconfigurations/ c o nnectionStat usBasedCreat e a c onnections t at us b ased alarmc o nf iguration.P UT/ ap i/alarmapp/alarmconfigurations/ c o nnectionStat usBased/{id}Up d ates a c onnections t at us b ased alarmc o nf iguration.D E LETE/ ap i/alarmapp/alarmconfigurations/ {id }D eletes t he alarmc o nf iguration with t heg iv en id.GE T/ ap i/alarmapp/alarmsGet s a list of all raisedalarms f or t he g ivenwo rk space o r d eviceres p ectively.
WAGO Cloud - REST-API DocumentationApp / Category Method / OperationAl arm 2.0 Al armConfi gurationsDescri ptionD E LETE/ ap i/alarmapp/alarmsD eletes all t he alarms f ort he g iven wo rkspace o rd ev ice respectively.D E LETE/ ap i/alarmapp/alarms/{id}D eletes t he alarm with t heg iv en id.P A TCH/ ap i/alarmapp/alarms/{id}Chang e t he s tatus of t healarm wit h t he given id.GE T/ ap i/alarmapp/alarmconfigurationsGet s t he c onfigured alarmc o nf igurations f or eithert he wo rkspace or t hed ev ice respectively.P OS T/ ap i/alarmapp/alarmconfigurations/ v alueBasedCreat es a v alue b asedalarm c onf iguration.P UT/ ap i/alarmapp/alarmconfigurations/ v alueBased/{id}Up d ates t he alarmc o nf iguration identif iedwit h t he g iven id wit h t heg iv en c onfiguration data.P OS T/ ap i/alarmapp/alarmconfigurations/ t imeIntervalBasedCreat es a t ime intervalb as ed alarm conf iguration.P UT/ ap i/alarmapp/alarmconfigurations/ t imeIntervalBased/{id}Up d ates t he alarmc o nf iguration identif iedwit h t he g iven id wit h t heg iv en c onfiguration data.P OS T/ ap i/alarmapp/alarmconfigurations/ t imeoutBasedCreat es an alarmc o nf iguration of t he t ypet imeout b ased within t hewo rk space wit h t he givenid entif ier.P UT/ ap i/alarmapp/alarmconfigurations/ t imeoutBased/{id}Up d ates t he alarmc o nf iguration with t heg iv en identif ier.P OS T/ ap i/alarmapp/alarmconfigurations/ alarmFlagsBasedCreat es an alarm f lagsalarm c onf iguration f or t hewo rk space.P UT/ ap i/alarmapp/alarmconfigurations/ alarmFlagsBased/{id}Up d ates t he alarm f lagsalarm c onf iguration f or t hewo rk space.
WAGO Cloud - REST-API DocumentationApp / Category Method / OperationDescri ptionAl arm 2.0 Al arm S tatusGE T/ ap i/alarmapp/alarmstatusGet s t he list of alarms t at uses c reat ed f or t heg iv en s ubscriptionP UT/ ap i/alarmapp/alarmstatusCreat es/Updates alarms t at uses f or t he g ivens ub scription
WAGO Cloud - REST-API Documentation3 REST-API Usage via Swagger3.1 OverviewS wagger is a t ool to manage RE ST-APIs. The WA GO Cloud REST-API o perationsc an b e us ed v ia t he S wagger UI, t he d etailed d ocumentation of t he REST -API is alsop art of t he S wagger UI. Y ou c an o pen t he WAGO Cloud RE ST-API v ia t he f ollowinglink : ht tps://cloud.wago.com/api/doc/index.html#/The S wagger UI Timeout is s et to 60 Minut es. Af ter t hat a new login is required .The new RE S T-API was introduced with WAGO Cloud Release 2. 2. The f ollowingc o mponents are s upport ed:Releas e 2. 2-Co re (Frame)-D ev ices-Telemet ry-A larmThe RE S T-API operations b efore release 2.2 s hould no longer be used and t hey aremark ed as d eprecated:-V 1 (d eprecated) - WA GO Cloud A PI-V 2 (d eprecated) - WA GO Cloud A PIB elo w s ections d escribe t he usage of a RE ST-API k ey, t he aut horization and t heus ag e of RE ST-API operations f or t he WA GO Cloud.
WAGO Cloud - REST-API Documentation3.2 REST -API KeyA new RE S T-A PI k ey is required t o b e ab le to us e t he new v ersion of t he REST-API.This k ey uniquely as signs t he RE ST-API t o a s ubscription. The f ollowing s tepsex p lain s hortly ho w t he k ey is g enerated and us ed.3.2. 1 Create an AP I KeyThe f irst t hing y ou need to d o is t o login t o t he WAGO Cloud and o pen t hes ub scription s ettings. Open t he t ab “RE ST-API” and c lick o n “Create”. A new k ey isg enerated f or t his s ubscription. Make s ure t hat y ou are S ubscription admin, b ecauseo nly t hen y ou c an c reate, d elete o r renew a k ey. A s a no rmal user you c an o nly s eet he c reated k ey. The s econdary k ey c an b e used if t he p rimary k ey is c urrently notav ailable.3.3 Authorization via SwaggerOp en t he RE ST-API S wagger UI and c lick o n “A uthorize”. S elect t he c heckbox of t heS c ope and c lick again on “A ut horize”. Y ou will b e redirected to a Microsoft p agewhere y o u will need to login with your WAGO Cloud c redentials.NOTE : D o not c hange t he “c lient id”, s ee below s creenshot.
WAGO Cloud - REST-API DocumentationA f ter you have s uccessfully s igned up y ou hav e t o copy t he RE ST-API k ey f rom t heWA GO Cloud into t he appropriate f ield and c lick again on “ A uthorize”.Y o u c an now work with t he WA GO Cloud RE ST-API. This is a p aid f eature. Ford et ailed inf ormation s ee t he WA GO Online Calculator.3.4 REST -API OperationsTo ex ec ut e t he WA GO Cloud REST-API operat ions, y ou have t o c hoose t heap p ropriat e d efinition, e.g. Core, D evice, Telemetry o r A larm and t hen s elect t heo p eration.
WAGO Cloud - REST-API DocumentationIf y o u s elect t he operation, t he p arameters and t he responses will be displayed. Themand atory parameters are marked with “ *required”. For s ome operations, d if ferentres ponse c odes are possible.A f ter t he s uccessf ul authentication and t he c lick o n “Try it out”, t he request b ody isd isplayed and c an b e c hanged. The o peration will b e perf ormed, if y ou c lick on t he“E x ecute” b utton. The res ult will be d isplayed under “Responses”.B elo w t he operations, t he s chemas are d isplayed. The s chemas d escribe t hep o ssible d ata t ypes with t heir at tribut es, e.g. s ubscription o r d evice. E numerationsc an als o be s hown in t he schema d ef inition.
WAGO Cloud - REST-API Documentation4 REST-API Scenarios via HTTP requestsThe f ollowing c hapt ers contain s tep -by-step manuals of ho w t o g et s t arted with t heWA GO Cloud RE ST-API.Thes e c hapters will s how you : Ho w t o authorize v ia REST-API Ho w t o get s ubscription and workspace inf ormation Ho w t o c reate a d evice in y our workspace Ho w t o get all c ommands s upported b y your d evice Ho w t o s end a c o mmand t o y our d evice Ho w t o get a wo rkspace s truct ure Ho w t o get t elemetry d ata4.1 Authorization via REST -APITo g et an aut horization t oken y ou c an s end a HTTP P OST req uest toht t ps://cloud.wago.com/api/token with t he c ontent t ype “application/x-www-f ormurlencoded” and t he f ollowing p arameters in t he request body: g rant type password us ername your-username p as sword your-password E x ample with c url:curl --location --request POST 'https://cloud.wago.com/api/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant type password' \--data-urlencode 'username ***' \--data-urlencode 'password ***'Y o u will receive a response in t he f ollowing f ormat:{"access token": "eyJ0eXAiOiJKV1QiLCJhbG.","name": " your-username ","token type": "bearer","expires in": 3600}The t o ken expires af ter 1 ho ur and y ou hav e t o ret rieve a new o ne af terwards.Note: We rec ommend c aching t he t oken and us ing it f or its f ull duration. If y oureq uest a new aut horization t oken f or each A PI request, t hrottling may occur.Us ing t he t oken in A PI requests:Fo r all requests t o t he WA GO Cloud RE ST A PI, y ou need t o add an A uthorizationHead er. The v alue of t he header is constructed wit h t he t oken type andac c ess token v alues, s eparated b y a whitespace, e.g.:
WAGO Cloud - REST-API DocumentationAuthorization: bearer eyJ0eXAiOiJKV1QiLCJhbG.4.2 Get Subscription and Workspace InformationFo r ex ecuting all A PIs, t he precondition wo uld b e you have already g et aut horized,whic h mentioned in c hapter 3. 3.To g et t he inf ormation f or a s ubscription, y ou need to k now t he s ubscription Id, whichis c reated af ter you registered your account. To g et t his inf ormat ion us e t he HTTPGE T / ap i/core/subscriptions/ {id} method.The req uired p arameter is s ubscription Id , which is a GUID s tring:[" mySubscriptionId "]If t he req uest is s uccessful, you will g et t he HTTP s tatus c ode 200. The responseb o dy would b e like t his:{"id": "ecfb9777-d46d-4ccf-bffa-3ff5961d38bf","name": "Sample subscription","description": " Sample subscription"}
WAGO Cloud - REST-API Documentation4.3 Create a DeviceTo c reat e a d evice, y ou need to invoke t he HTTP P OST / api/deviceapp/devicesmet hod. For t he parameter, y our need give t he workspace Id :[" workspaceId "]The req uest body s hould c ontains t he f older Id and device name you def ined:{"folder": " yourFolderId ","name": " yourDeviceName "}If t he req uest is s uccessful, you will g et t he HTTP s tatus c ode 201. The responseb o dy would b e like t his:{"name": "Device X","key": "30etXnPPiKjjOlzrdoRpkqxXQew7Em6qZ zDQBn3yL8 "}4.4 Get all Commands Supported for a DeviceTo g et all commands s upported f or a d evice us e t he HTTP Get/ ap i/deviceapp/devices/{id}/commands method. For t he p arameter you need t op ro vide t he device i d.[" deviceId "]If t he req uest is s uccessful, you will g et t he HTTP s tatus c ode 200. The responseb o dy would b e like t his:[{"id": 502,"name": "StartDataSubmission","commandRequest": [],"commandResponse": [{"name": "Started","type": "string"}]},{"id": 501,"name": "StopDataSubmission","commandRequest": [],"commandResponse": [{"name": "Stopped","type": "string"}]},{"id": 256,"name": "ChangeSamplingRate","commandRequest": [{"name": "SampleIntervalMilliseconds","type": "dint"},
WAGO Cloud - REST-API Documentation{"name": "CollectionId","type": "dint"}],"commandResponse": [{"name": "Result","type": "string"},{"name": "CollectionId","type": "string"},{"name": "SampleIntervalMilliseconds","type": "string"}]},{"id": 257,"name": "ChangePublishingRate","commandRequest": [{"name": "PublishIntervalMilliseconds","type": "dint"},{"name": "CollectionId","type": "dint"}],"commandResponse": [{"name": "Result","type": "string"},{"name": "CollectionId","type": "string"},{"name": "PublishIntervalMilliseconds","type": "string"}]},{"id": 500,"name": "DeleteController","commandRequest": [],"commandResponse": []},{"id": 504,"name": "GetNodeInfo","commandRequest": [],"commandResponse": [{"name": "TransferTriggered","type": "string"}]},{"id": 503,"name": "SetHeartbeatInterval","commandRequest": [
WAGO Cloud - REST-API Documentation{"name": "IntervalInSeconds","type": "string"}],"commandResponse": [{"name": "IntervalInSeconds","type": "string"}]},{"id": 509,"name": "StartRemoteAccessMediator","commandRequest": [{"name": "URL","type": "string"}],"commandResponse": [{"name": "Started","type": "bool"}]},{"id": 510,"name": "StopRemoteAccessMediator","commandRequest": [],"commandResponse": [{"name": "Stopped","type": "bool"}]}]4.5 Send a Command to the DeviceTo s end a c ommand to t he device, you need t o invoke t he HTTP P UT/ ap i/deviceapp/devices/{id}/commands/{command} method.Fo r t he p arameters, you need t o p rovide t he device id and t he k ey of t he command tos end . The s ystem s upports 9 g eneral def ault commands described in below t able:Co mmand NameCo mmand IDChang eSamplingRate256Chang ePublishingRate257D eleteController500S t opDat aSubmission501S t artDataSubmission502S et HeartbeatInterval503Get NodeInf o504S t art RemoteAccessMediator509
WAGO Cloud - REST-API DocumentationS t opRemoteAccessMediator510There are d if ference b etween commands f or t he command request and c ommandres ponse. If you are not f amiliar with t he command request p art you c an go t o 4. 7 t og et t he overview of all b asic commands.Fo r ins tance, if y ou want t o s top t he d ata s ubmission f or a running device , you needt o p rovide: d ev ice ID , e.g. 84f 7b993-d5dc-499f -9d5d- c o mmand ID , e. g. 501 c o mmand request in t he request body: “[ ]”If t he req uest is s uccessful, you will g et t he HTTP s tatus c ode 200. The responseb o dy would b e like t his:{"parameters": [{"name": "Stopped","value": "true"}]}S inc e t he WAGO Cloud release 3. 4 t he d evice app 2. 0 is available. This new v ersioninc ludes additional return c odes. If a d evice is of fline and a c ommand is s ent to t hisd ev ice v ia t he res t A PI, t he us er also receives an immediate response. The f ollowingres ponse c odes were introduced: " 408 - Req uest Timeout": Ind icates t hat t he s erver did no t receive a c o mpletereq uest f rom t he c lient within t he s erver’s allotted t imeout p eriod ." 409 - Co nf lict" : The request c ould no t be c ompleted d ue t o a c onf lict with t hec urrent s tate of t he resource." 429 - To o Many Requests": The us er has s ent t oo many requests in a g ivenamo unt of t ime." 500 - Int ernal S erver E rror": The s erver encountered an unexpected conditionwhic h p revented it f rom f ulf illing t he request." 504 Gat eway Timeout": The s erver is acting as a g ateway and c annot get ares ponse in t ime f or a req uest.The c urrent response c odes 200, 202, 400, 404 s t ill remain .Ot her ret urn codes may also have c hanged in t he 2. 0 v ersion. The f ollowingo p erations are available in t he S wagger UI d evice app 2.0:-P OS T/ api/deviceapp/devices/{id}/commands/{command}GE T/ api/deviceapp/devices/{deviceId}/commandResponse/ {c ommandResponseId}P OS T/ api/deviceapp/devices/{deviceId}/commandsAsync/ {command}4.6 Get the Workspace StructureTo g et t he workspace s tructure us e t he HTTP Get / api/core/workspaces/{id}/structuremet hod. The workspace id has to b e passed as a p arameter:
WAGO Cloud - REST-API Documentation[" workspaceId "]Y o u c an add an o ptional p aramet er “parent Id ” if y ou want t o g et t he node s truct urewhere t o s tart t he s earch f rom:[" parentId "]If t he req uest is
WAGO Cloud - REST-API Documentation 1 Overview Besides managing the devices in the WAGO Cloud Web-Portal, it is also possible to manage the WAGO Cloud and the data via the REST-API. The REST-API provides the following use cases and functions: Use cases of the REST-API: Scripting e.g. automatic device registration Custom applications
