web Requests
The Notecard can perform requests and obtain responses from 3rd-party APIs and
services with the web API requests.
web CellCell+WiFiWiFi
Performs an HTTP or HTTPS request against an external endpoint, with the ability to specify any valid HTTP method.
note
warningThe Notecard must have an active connection to Notehub while performing any web.* request. Please consult this guide for more information.
content
string (optional)
The MIME type of the body or payload of the response. Default is application/json.
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).
route
string
Alias for a Proxy Route in Notehub.
{
"req": "web",
"method": "GET",
"route": "weatherInfo",
"name": "/getLatest"
}J *req = NoteNewRequest("web");
JAddStringToObject(req, "method", "GET");
JAddStringToObject(req, "route", "weatherInfo");
JAddStringToObject(req, "name", "/getLatest");
NoteRequest(req);req = {"req": "web"}
req["method"] = "GET"
req["route"] = "weatherInfo"
req["name"] = "/getLatest"
rsp = card.Transaction(req)Performs a simple HTTP or HTTPS request and returns the response.
Response Members
body
object
The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.
cobs
integer
The size of the COBS-encoded data (in bytes).
length
integer
The length of the returned binary payload (in 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.
result
integer
The HTTP Status Code
{
"result": 200,
"body": {
"temp": 75,
"humidity": 49
}
}web.delete CellCell+WiFiWiFi
Performs a simple HTTP or HTTPS DELETE request against an external endpoint, and returns the response to the Notecard.
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.
content
string (optional, default application/json)
The MIME type of the body or payload of the response. Default is application/json.
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.
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).
note
string (optional)
The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).
route
string
Alias for a Proxy Route in Notehub.
seconds
integer (optional, default 90)
If specified, overrides the default 90 second timeout.
{
"req": "web.delete",
"route": "SensorService",
"name": "/deleteReading?id=1"
}J *req = NoteNewRequest("web.delete");
JAddStringToObject(req, "route", "SensorService");
JAddStringToObject(req, "name", "/deleteReading?id=1");
NoteRequest(req);req = {"req": "web.delete"}
req["route"] = "SensorService"
req["name"] = "/deleteReading?id=1"
rsp = card.Transaction(req)Performs a simple HTTP or HTTPS DELETE request and returns the response.
Response Members
body
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.
result
integer
The HTTP Status Code
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.
{
"result": 204
}web.get CellCell+WiFiWiFi
Performs a simple HTTP or HTTPS GET request against an external endpoint, and returns the response to the Notecard.
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.
body
object (optional)
The JSON body to send with the request.
content
string (optional)
The MIME type of the body or payload of the response. Default is application/json.
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.
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.
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).
note
string (optional)
The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).
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.
route
string
Alias for a Proxy Route in Notehub.
seconds
integer (optional)
If specified, overrides the default 90 second timeout.
{
"req": "web.get",
"route": "weatherInfo",
"name": "/getLatest"
}J *req = NoteNewRequest("web.get");
JAddStringToObject(req, "route", "weatherInfo");
JAddStringToObject(req, "name", "/getLatest");
NoteRequest(req);req = {"req": "web.get"}
req["route"] = "weatherInfo"
req["name"] = "/getLatest"
rsp = card.Transaction(req)Performs a simple HTTP or HTTPS GET request and returns the response.
Response Members
body
object
The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.
cobs
integer
The size of the COBS-encoded data (in bytes).
length
integer
The length of the returned binary payload (in bytes).
payload
string
A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.
result
integer
The HTTP Status Code.
{
"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.
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.
body
object (optional)
The JSON body to send with the request.
content
string (optional, default application/json)
The MIME type of the body or payload of the response. Default is application/json.
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.
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.
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).
note
string (optional)
The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).
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.
payload
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.
route
string
Alias for a Proxy Route in Notehub.
seconds
integer (optional, default 90)
If specified, overrides the default 90 second timeout.
status
string (optional)
A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt.
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.
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.
{
"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");
NoteRequest(req);req = {"req": "web.post"}
req["route"] = "SensorService"
req["name"] = "/addReading"
rsp = card.Transaction(req)Performs a simple HTTP or HTTPS POST request and returns the response.
Response Members
body
object
The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.
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).
payload
base64 string
A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.
result
integer
The HTTP Status Code.
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.
{
"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.
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.
body
object (optional)
The JSON body to send with the request.
content
string (optional, default application/json)
The MIME type of the body or payload of the response. Default is application/json.
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.
max
integer (optional, default 8192)
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.
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).
note
string (optional)
The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).
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.
payload
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.
route
string
Alias for a Proxy Route in Notehub.
seconds
integer (optional, default 90)
If specified, overrides the default 90 second timeout.
status
string (optional)
A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt.
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.
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.
{
"req": "web.put",
"route": "SensorService",
"name": "/updateReading",
"body": {
"id": 1234,
"temp": 72.32,
"humidity": 32.2
}
}J *req = NoteNewRequest("web.put");
JAddStringToObject(req, "route", "SensorService");
JAddStringToObject(req, "name", "/updateReading");
NoteRequest(req);req = {"req": "web.put"}
req["route"] = "SensorService"
req["name"] = "/updateReading"
rsp = card.Transaction(req)Performs a simple HTTP or HTTPS PUT request and returns the response.
Response Members
body
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.
result
integer
The HTTP Status Code.
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.
{
"result": 204
}