homechevron_rightDocschevron_rightAPI Referencechevron_rightNotecard APIchevron_rightweb Requests - API Reference

web Requests

The Notecard can perform requests and obtain responses from 3rd-party APIs and services with the web API requests.

Notecard Firmware Version:

warning

The Notecard must have an active connection to Notehub while performing any web.* request. Please consult this guide for more information.

web.get CellCell+WiFiWiFi

Performs a simple HTTP or HTTPS GET request against an external endpoint, and returns the response to the Notecard.

Arguments

`route`

string

Alias for a Proxy Route in Notehub.

`name`

string (optional)

A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /getLatest?id=1).

`content`

string (optional)

The MIME type of the body or payload of the response. Default is application/json.

`seconds`

integer (optional)

If specified, overrides the default 90 second timeout.

`async`

boolean (optional)

If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.

`binary`

boolean (optional)

If true, the Notecard will return the response stored in its binary buffer.

Learn more in this guide on Sending and Receiving Large Binary Objects.

`offset`

integer (optional)

Used along with binary:true and max, sent as a URL parameter to the remote endpoint. Represents the number of bytes to offset the binary payload from 0 when retrieving binary data from the remote endpoint.

`max`

integer (optional)

Used along with binary:true and offset, sent as a URL parameter to the remote endpoint. Represents the number of bytes to retrieve from the binary payload segment.

`file`

string (optional)

The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response.

`note`

string (optional)

The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).

Example

JSON

{
  "req": "web.get",
  "route": "weatherInfo",
  "name": "/getLatest"
}

C/C++

J *req = NoteNewRequest("web.get");
JAddStringToObject(req, "route", "weatherInfo");
JAddStringToObject(req, "name", "/getLatest");
NoteRequest(req);

Python

req = {"req": "web.get"}
req["route"] = "weatherInfo"
req["name"] = "/getLatest"
rsp = card.Transaction(req)

Response Members

`result`

integer

The HTTP Status Code.

`body`

JSON object

The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.

`payload`

base64 string

A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.

`length`

integer

The length of the returned binary payload (in bytes).

`cobs`

integer

The size of the COBS-encoded data (in bytes).

Example Response

{
  "result": 200,
  "body": { "temp": 75, "humidity": 49 }
}

web.post CellCell+WiFiWiFi

Performs a simple HTTP or HTTPS POST request against an external endpoint, and returns the response to the Notecard.

Arguments

`route`

string

Alias for a Proxy Route in Notehub.

`name`

string (optional)

A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /addReading?id=1).

`body`

JSON object (optional)

The JSON body to send with the request.

`payload`

base64 string (optional)

A base64-encoded binary payload. A web.post may have either a body or a payload, but may NOT have both. Be aware that Notehub will decode the payload as it is delivered to the endpoint.

Learn more about sending large binary objects with the Notecard.

`content`

string (optional)

The MIME type of the body or payload of the response. Default is application/json.

`seconds`

integer (optional)

If specified, overrides the default 90 second timeout.

`total`

integer (optional)

When sending large payloads to Notehub in fragments across several web.post requests, the total size, in bytes, of the binary payload across all fragments.

`offset`

integer (optional)

When sending payload fragments, the number of bytes of the binary payload to offset from 0 when reassembling on the Notehub once all fragments have been received.

`status`

string (optional)

A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt.

`max`

integer (optional)

The maximum size of the response from the remote server, in bytes. Useful if a memory-constrained host wants to limit the response size.

`verify`

boolean (optional)

true to request verification from Notehub once the payload or payload fragment is received. Automatically set to true when status is supplied.

`async`

boolean (optional)

If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.

`binary`

boolean (optional)

If true, the Notecard will send all the data in the binary buffer to the specified proxy route in Notehub.

Learn more in this guide on Sending and Receiving Large Binary Objects.

`file`

string (optional)

The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response.

`note`

string (optional)

The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).

Example

JSON

{
  "req": "web.post",
  "route": "SensorService",
  "name": "/addReading",
  "body": { "temp": 72.32, "humidity": 32.2 }
}

C/C++

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);

Python

req = {"req": "web.post"}
req["route"] = "SensorService"
req["name"] = "/addReading"
req["body"] = {"temp":72.32, "humidity":32.2}
rsp = card.Transaction(req)

Response Members

`result`

integer

The HTTP Status Code.

`body`

JSON object

The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.

`payload`

base64 string

A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.

`status`

string

If a payload is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption.

`cobs`

integer

If the web transaction returns a binary payload, cobs is the size of the COBS-encoded payload (in bytes).

`length`

integer

If the web transaction returns a binary payload, length is the size of the unencoded payload (in bytes).

Example Response

{
  "result": 201
}

web.put CellCell+WiFiWiFi

Performs a simple HTTP or HTTPS PUT request against an external endpoint, and returns the response to the Notecard.

Arguments

`route`

string

Alias for a Proxy Route in Notehub.

`name`

string (optional)

A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /updateReading?id=1).

`body`

JSON object (optional)

The JSON body to send with the request.

`payload`

base64 string (optional)

A base64-encoded binary payload. A web.put may have either a body or a payload, but may NOT have both. Be aware that Notehub will decode the payload as it is delivered to the endpoint.

Learn more about sending large binary objects with the Notecard.

`content`

string (optional)

The MIME type of the body or payload of the response. Default is application/json.

`seconds`

integer (optional)

If specified, overrides the default 90 second timeout.

`total`

integer (optional)

When sending large payloads to Notehub in fragments across several web.put requests, the total size, in bytes, of the binary payload across all fragments.

`offset`

integer (optional)

When sending payload fragments, the number of bytes of the binary payload to offset from 0 when reassembling on the Notehub once all fragments have been received.

`status`

string (optional)

A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt.

`max`

integer (optional)

The maximum size of the response from the remote server, in bytes. Useful if a memory-constrained host wants to limit the response size. Default (and maximum value) is 8192.

`verify`

boolean (optional)

true to request verification from Notehub once the payload or payload fragment is received. Automatically set to true when status is supplied.

`async`

boolean (optional)

If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.

`file`

string (optional)

The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response.

`note`

string (optional)

The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).

Example

JSON

{
  "req": "web.put",
  "route": "SensorService",
  "name": "/updateReading",
  "body": { "id": 1234, "temp": 72.32, "humidity": 32.2 }
}

C/C++

J *req = NoteNewRequest("web.put");
JAddNumberToObject(req, "id", 1234);
JAddStringToObject(req, "route", "SensorService");
JAddStringToObject(req, "name", "/updateReading");

J *body = JCreateObject();
JAddNumberToObject(body, "temp", 72.32");
JAddNumberToObject(body, "humidity", 32.2);
JAddItemToObject(req, "body", body);

NoteRequest(req);

Python

req = {"req": "web.put"}
req["route"] = "SensorService"
req["name"] = "/updateReading"
req["body"] = {"id":1234, "temp":72.32, "humidity":32.2}
rsp = card.Transaction(req)

Response Members

`result`

integer

The HTTP Status Code.

`body`

JSON object

The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.

`payload`

base64 string

A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.

`status`

string

If a payload is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption.

Example Response

{
  "result": 204
}

web.delete CellCell+WiFiWiFi

Performs a simple HTTP or HTTPS DELETE request against an external endpoint, and returns the response to the Notecard.

Arguments

`route`

string

Alias for a Proxy Route in Notehub.

`name`

string (optional)

A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /deleteReading?id=1).

`content`

string (optional)

The MIME type of the body or payload of the response. Default is application/json.

`seconds`

integer (optional)

If specified, overrides the default 90 second timeout.

`async`

boolean (optional)

If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.

`file`

string (optional)

The name of the local-only Database Notefile (.dbx) to be used if the web request is issued asynchronously and you wish to store the response.

`note`

string (optional)

The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).

Example

JSON

{
  "req": "web.delete",
  "route": "SensorService",
  "name": "/deleteReading?id=1"
}

C/C++

J *req = NoteNewRequest("web.delete");
JAddStringToObject(req, "route", "SensorService");
JAddStringToObject(req, "name", "/deleteReading?id=1");

NoteRequest(req);

Python

req = {"req": "web.delete"}
req["route"] = "SensorService"
req["name"] = "/deleteReading?id=1"
rsp = card.Transaction(req)

Response Members

`result`

integer

The HTTP Status Code.

`body`

JSON object

The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.

`payload`

base64 string

A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.

`status`

string

If a payload is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption.

Example Response

{
  "result": 204
}

More information:

Web Transactions Guide

web CellCell+WiFiWiFi

Performs an HTTP or HTTPS request against an external endpoint, with the ability to specify any valid HTTP method.

note

Please see the additional argument options available for GET, POST, PUT, and DELETE requests in the documentation provided.

Arguments

`route`

string

Alias for a Proxy Route in Notehub.

`method`

string

The HTTP method of the request. Must be one of GET, PUT, POST, DELETE, PATCH, HEAD, OPTIONS, TRACE, or CONNECT.

`name`

string (optional)

A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. /getLatest?id=1).

`content`

string (optional)

The MIME type of the body or payload of the response. Default is application/json.

Example

JSON

{
  "req": "web",
  "method": "GET",
  "route": "weatherInfo",
  "name": "/getLatest"
}

C/C++

J *req = NoteNewRequest("web");
JAddStringToObject(req, "method", "GET");
JAddStringToObject(req, "route", "weatherInfo");
JAddStringToObject(req, "name", "/getLatest");
NoteRequest(req);

Python

req = {"req": "web"}
req["method"] = "GET"
req["route"] = "weatherInfo"
req["name"] = "/getLatest"
rsp = card.Transaction(req)

Response Members

`result`

integer

The HTTP Status Code.

`body`

JSON object

The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.

`payload`

base64 string

A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.

`length`

integer

The length of the returned binary payload (in bytes).

`cobs`

integer

The size of the COBS-encoded data (in bytes).

Example Response

{
  "result": 200,
  "body": { "temp": 75, "humidity": 49 }
}

var Requests