Topic: DMD0482
REST API
Ethernet-equipped BRX CPUs contain an HTTP-based RESTful API (REpresentational State Transfer, Application Programming Interface) that will return the contents of PLC memory locations in JSON formatted records. The REST API is accessed by a web browser using a URL with the appropriate parameters.
The REST API can:
read any bit location: will return 0 for OFF or 1 for ON. Can also read a block of up to 128 contiguous BITs.
read any numeric location: the value will be either signed decimal or floating point (real) depending on the data type of the element being read. Can also read a block of up to 128 contiguous numeric locations.
read any system-defined String or user-defined String.
read any system-defined or user-defined Structure with options to control how many of the structure fields will be in the returned data.
read any individual structure field from any system-defined or user-defined Structure.
read any Bit or Numeric location using its assigned Nickname. If needed, access to Nicknamed locations can be disabled in the Documentation Editor's memory access settings.
The REST API does not allow write access to any CPU memory location.
Reading a single element from the PLC into an Object:
Format:
/data/json?MyName = <PLC Element>
Example:
<PLC IP Address>/data/json?MyDeeEssTeeZero=DST0
Response JSON record is an object containing the element's data value.
{
"MyDeeEssTeeZero":14437656
}
Reading multiple elements from the PLC into a series of Objects:
Format:
/data/json?1stName = <1st Element>&2ndName = <2nd Element>&3rdName = <3rd Element> ...
Example:
<PLC IP Address>/data/json?MyDeeEssTeeZero=DST0&MyYTen=Y10&MyStringFour=SS4
Response JSON record are objects containing the specified elements' data values.
{
"MyDeeZero":14437656,
"MyYTen":0,
"MyStringFour":"My Dog Has Fleas"
}
Reading a block of contiguous elements ( ,<count value> ) from the PLC into an Array (maximum of 128 consecutive elements):
Format:
/data/json?MyName = <PLC Element>,count
Example:
<PLC IP Address>/data/json?FirstTenDs=DST0,10&SomeExs=x10,16&FourStrings=SS4,4
Response JSON record is an array containing the specified number of consecutive elements' data values. If the elements are Strings, each String will be enclosed in a pair of double quotes.
{
"FirstTenDs":[22911329,50,13,8593,46,0,32768,0,0,0],
"SomeExs":[0,1,1,1,0,0,0,0,0,0,0,0,0,0,0,1],
"FourStrings":["My Dog Has Fleas","Your Dog Has Fleas","So Does His","Hers Does Too"]
}
Note: If the elements are Strings, each String will be enclosed in a pair of double quotes. If the Strings contain nested quotes, each quote will be 'escaped' with a slash, e.g. $"puppy$" will be output as \"puppy\".
Reading a block of contiguous String elements in raw mode ( ,R<count value> ) from the PLC into an Array (maximum of 128 consecutive elements):
Format:
/data/json?MyName = <PLC Element>,R<count>
Example:
<PLC IP Address>/data/json?FourStrings=SS4,R4
Response JSON record is an array containing the specified number of consecutive Strings' contents. The individual Strings will NOT be enclosed in double quotes.
{
"FourStrings":[My Dog Has Fleas,Your Dog Has Fleas,So Does His,Hers Does Too]
}
Note: If the elements are Strings, each String will be enclosed in a pair of double quotes. If the Strings contain nested quotes, each quote will be 'escaped' with a slash, e.g. $"puppy$" will be output as \"puppy\".
Reading one or more structures from the PLC into Objects: Short list of fields ( S )
Format:
/data/json?MyStruct= <PLC structure>,S
Example:
<PLC IP Address>/data/json?MyMain=$Main,S&MyTimer=T0
Response JSON record is an object containing the most commonly used structure field names and their current data values.
{
"MyMain":{"RanThisScan":1,"Done":0,"TimeSlice":65535,"S0_15":0,"S16_31":0,"S32_47":0,"S48_63":0,"S64_79":0,"S80_95":0,"S96_111":0,"S112_127":0},
"MyTimer":{"Acc":0,"Done":0}
}
Reading one or more structures from the PLC into Objects: Long list of fields ( L )
Format:
/data/json?MyStruct= <PLC structure>,L
Example:
<PLC IP Address>/data/json?MyMain=$Main.L&MyTimer=T0,L
Response JSON record is an object containing the most of the structure field names and their current data values.
{
"MyMain":{"RanThisScan":1,"Done":0,"FirstRun":0,"TimeSlice":65535,"ScanCounter":37579023,"RunCounter":0,"S0_15":0,"S16_31":0,"S32_47":0,"S48_63":0,"S64_79":0,"S80_95":0,"S96_111":0,"S112_127":0},
"MyTimer":{"Acc":0,"Done":0,"Zero":1,"Timing":0,"Reset":1,"TT":0,"EN":0,"DN":0}
}
Reading one or more structures from the PLC into Objects: list All fields ( A )
Format:
/data/json?MyStruct= <PLC structure>,A
Example:
<PLC IP Address>/data/json?MyMain=$Main,A&MyTimer=T0,A
Response JSON record is an object containing all of the structure field names and their current data values.
{
"MyMain":{"Running":1,"RanThisScan":1,"Done":0,"FirstScan":0,"FirstRun":0,"DoneThisScan":0,"InstrSuspend":0,"DebugSuspend":0,"TimeSlice":65535,"ScanCounter":41210774,"RunCounter":0,
"S0_15":0,"S16_31":0,"S32_47":0,"S48_63":0,"S64_79":0,"S80_95":0,"S96_111":0,"S112_127":0,"S0":0,"S1":0,"S2":0,"S3":0,"S4":0,"S5":0,"S6":0,"S7":0,"S8":0,"S9":0,
"S10":0,"S11":0,"S12":0,"S13":0,"S14":0,"S15":0,"S16":0,"S17":0,"S18":0,"S19":0,"S20":0,"S21":0,"S22":0,"S23":0,"S24":0,"S25":0,"S26":0,"S27":0,"S28":0,"S29":0,"S30":0,
"S31":0,"S32":0,"S33":0,"S34":0,"S35":0,"S36":0,"S37":0,"S38":0,"S39":0,"S40":0,"S41":0,"S42":0,"S43":0,"S44":0,"S45":0,"S46":0,"S47":0,"S48":0,"S49":0,"S50":0,"S51":0,
"S52":0,"S53":0,"S54":0,"S55":0,"S56":0,"S57":0,"S58":0,"S59":0,"S60":0,"S61":0,"S62":0,"S63":0,"S64":0,"S65":0,"S66":0,"S67":0,"S68":0,"S69":0,"S70":0,"S71":0,"S72":0,
"S73":0,"S74":0,"S75":0,"S76":0,"S77":0,"S78":0,"S79":0,"S80":0,"S81":0,"S82":0,"S83":0,"S84":0,"S85":0,"S86":0,"S87":0,"S88":0,"S89":0,"S90":0,"S91":0,"S92":0,"S93":0,
"S94":0,"S95":0,"S96":0,"S97":0,"S98":0,"S99":0,"S100":0,"S101":0,"S102":0,"S103":0,"S104":0,"S105":0,"S106":0,"S107":0,"S108":0,"S109":0,"S110":0,"S111":0,"S112":0,
"S113":0,"S114":0,"S115":0,"S116":0,"S117":0,"S118":0,"S119":0,"S120":0,"S121":0,"S122":0,"S123":0,"S124":0,"S125":0,"S126":0,"S127":0},
"MyTimer":{"Acc":0,"Done":0,"Zero":1,"Timing":0,"Reset":1,"TT":0,"EN":0,"DN":0}
}
Reading one or more individual fields of a structure from the PLC into a series of Objects:
Format:
/data/json?MyStructField= <PLC structure>.field
Example:
<PLC IP Address>/data/json?MyMainDidItRun=$Main.RanThisScan&MyTimerZeroCurrent=T0.Acc
Response JSON record is an object containing the current data value of the specified field.
{
"MyMainDidItRun":1,
"MyTimerZeroCurrent":467
}
See Also:
The BRX CPU's On-board Web Server
The BRX CPU's HTTP-based REST API
Related Topics:
FTPGET - Retrieve File from Remote
HTTPCMD - HTTP Request / Response with Server
MQTTPUB - IoT Publish MQTT Topics
MQTTSUB - IoT Subscribe to MQTT Topics