Web Transactions
If your host needs to perform web requests to a 3rd party API or service,
the Notecard can facilitate these requests with the web.get
, web.put
,
and web.post
requests. Use of these requests in the Notecard API requires
the following:
- The Notecard must be in
continuous
mode (via ahub.set
request) and connected to Notehub. If any of theweb.*
requests are issued to a Notecard not incontinuous
mode or not connected, an error will be returned.
{"err":"web operations require being online (hub.set)"}
- The endpoint to the 3rd party API or service must be configured as a proxy Route in Notehub as a "Proxy for Device Web Requests" type. This allows the host to avoid hardcoded URLs, keys, and certificates, while relying on Notehub secure authentication mechanisms for performing requests.
Once the device is in continuous
mode and proxy Route is created,
use web.get
, web.put
or web.post
in accordance with the requirements of
the final endpoint.
For example, the Route shown above creates a proxy to a GET
request to
weather
endpoint of the OpenWeatherMap API.
To call this Route, a web.get
request should be used. The route
argument
corresponds to the Route Alias specified when the proxy Route is created.
{
"req": "web.get",
"route": "GetWeather"
}
For all web requests, the Notecard returns the HTTP Status Code in the result
field. If the response also contains a body, that body is provided in the
body
field.
{
"result": 200,
"body":{
"base": "stations",
"clouds": {"all":75},
"coord": {"lat":42.577600,"lon":-70.871340},
"name": "Beverly",
"weather":[
{"description":"broken clouds","icon":"04d","id":803,"main":"Clouds"}
],
"wind":{"deg":240,"speed":5.1}
}
}
For web.put
and web.post
requests, a JSON body can be provided using the
body
argument.
{
"req": "web.post",
"route": "ProvisonDevice"
"body": {"device":"dev123455"}
}
After performing a web request, don't forget to set your Notecard back into
a non-continuous mode, if needed, using hub.set
.