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.

note

Web transactions are not supported on the Notecard LoRa.

Requirements for Using Web Transactions

Use of these requests in the Notecard API requires the following:

1) The Notecard must be in continuous mode.

You can place your Notecard into continuous mode using the hub.set request as shown below.

{
  "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)

2) The Notecard must be connected.

When you place a Notecard in continuous mode it immediately starts making a connection to Notehub. If you attempt to make any web.* requests before this connection completes you'll receive the following error.

{ "err": "web operations require being online (hub.set)" }

You can check whether your Notecard is connected using the hub.status request.

{"req": "hub.status"}

J *req = NoteNewRequest("hub.status");

NoteRequest(req);

req = {"req": "hub.status"}
rsp = card.Transaction(req)

When the hub.status request returns "connected": true, you know your Notecard has made a connection with Notehub and you are safe to perform web.* requests.

{"req":"hub.status"}

{"connected":true}

3) The endpoint to the 3rd-party API or cloud service must be configured as a proxy Route in Notehub as a "Proxy for Notecard Web Requests" type.

This allows the host to avoid hardcoded URLs, keys, and certificates, while relying on Notehub secure authentication mechanisms for performing requests.

With the three steps complete, you can now use the web.get, web.put, web.post, or web.delete requests in accordance with the requirements of the final endpoint.

For example, the Route shown above creates a proxy to a GET request to a weather endpoint of the OpenWeatherMap API. The route argument corresponds to the 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": "GetWeather"
}

J *req = NoteNewRequest("web.get");
JAddStringToObject(req, "route", "GetWeather");

NoteRequest(req);

req = {"req": "web.get"}
req["route"] = "GetWeather"

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.

warning

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
  }
 }
}

note

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)

The Notecard does not store the result of web transactions in Notes. However, Notehub logs all web transactions as events, and you can view them in the Events view of your Notehub project.

If you double click an event and visit its Route log tab, you can view the result of your web transaction in the Notehub UI.

Finally, when you're done performing a web request, don't forget to set your Notecard back into a non-continuous mode, if needed, using hub.set.

Consult the web Requests API reference for more extensive information on using the web.* APIs.

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.