Web Transactions
If your host needs to perform web requests (e.g. GET
, PUT
, POST
, or
DELETE
) with a 3rd party API or cloud service, the Notecard can facilitate
these requests with the web.get
, web.put
, web.post
, and web.delete
APIs.
Consult the web Requests API reference for more extensive information on using the
web.*
APIs.
Requirements for Using Web Transactions
Use of these requests in the Notecard API requires the following:
1) The Notecard must be in continuous
mode and connected to Notehub.
For example:
{
"req": "hub.set",
"product": "com.your-company.your-name:your_product",
"mode": "continuous"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "product", "com.your-company.your-name:your_product");
JAddStringToObject(req, "mode", "continuous");
NoteRequest(req);
req = {"req": "hub.set"}
req["product"] = "com.your-company.your-name:your_product"
req["mode"] = "continuous"
card.Transaction(req)
If any of the web.*
requests are issued to a Notecard not in continuous
mode or not connected, an error will be returned:
{ "err": "web operations require being online (hub.set)" }
2) The endpoint to the 3rd party API or cloud 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 the proxy Route is created,
use web.get
, web.put
, web.post
, or web.delete
in accordance with the
requirements of the final endpoint.
For example, the Route shown above creates a proxy to a GET
request to the
weather
endpoint of the OpenWeatherMap API.
The route
argument corresponds to the Route Alias specified when the proxy
Route is created.
Note that you may optionally enable caching so that web.get
requests
return cached results to reduce latency and provide you with more control over
Consumption Credit
usage (i.e. cached responses do not cost CCs). When handling a web.get
request
with caching enabled, Notehub honors the Cache-Control
response header as per
RFC7234 with a
minimum cache TTL of 5 minutes.
{
"req": "web.get",
"route": "weatherInfo"
}
J *req = NoteNewRequest("web.get");
JAddStringToObject(req, "route", "weatherInfo");
NoteRequest(req);
req = {"req": "web.get"}
req["route"] = "weatherInfo"
rsp = card.Transaction(req)
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.
The Notecard can only accept valid JSON in response to a GET
, POST
, or PUT
request unless you override the default content
argument of application/json
with the appropriate MIME type.
{
"result": 200,
"body": {
"base": "stations",
"clouds": {
"all": 75
},
"coord": {
"lat": 42.5776,
"lon": -70.87134
},
"name": "Beverly",
"weather": [
{
"description": "broken clouds",
"icon": "04d",
"id": 803,
"main": "Clouds"
}
],
"wind": {
"deg": 240,
"speed": 5.1
}
}
}
Data returned by a proxy Route is delivered to the Notecard unmodified. To preserve power and data, make sure the APIs you're working with return only the data needed by your host, if possible.
For web.put
and web.post
requests, a JSON body OR base64-encoded payload can
be provided using the body
or payload
arguments. Unlike the note.add
API,
you cannot use both at the same time in a single web transaction.
{
"req": "web.post",
"route": "SensorService",
"name": "/addReading",
"body": { "temp": 72.32, "humidity": 32.2 }
}
J *req = NoteNewRequest("web.post");
JAddStringToObject(req, "route", "SensorService");
JAddStringToObject(req, "name", "/addReading");
J *body = JCreateObject();
JAddNumberToObject(body, "temp", 72.32);
JAddNumberToObject(body, "humidity", 32.2);
JAddItemToObject(req, "body", body);
NoteRequest(req);
req = {"req": "web.post"}
req["route"] = "SensorService"
req["name"] = "/addReading"
req["body"] = {"temp":72.32, "humidity":32.2}
rsp = card.Transaction(req)
After performing a web request, don't forget to set your Notecard back into
a non-continuous mode, if needed, using hub.set
.
Sending Large Payloads to Notehub
Consult our guide on Sending and Receiving Large Binary Objects if your application needs to send large binary payloads to Notehub.
Inbound Requests & Shared Data Low Power Design