web Requests
The Notecard can perform requests and obtain responses from 3rd-party APIs and
services with the web
API requests.
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.
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.
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).
{
"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)
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).
{
"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.
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.
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).
{
"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)
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.
{
"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.
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.
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).
{
"req": "web.put",
"route": "SensorService",
"name": "/updateReading",
"body": { "id": 1234, "temp": 72.32, "humidity": 32.2 }
}
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);
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.
{
"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.
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.
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).
{
"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)
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.
{
"result": 204
}
web CellCell+WiFiWiFi
Performs an HTTP or HTTPS request against an external endpoint, with the ability to specify any valid HTTP method.
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
.
{
"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)
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).
{
"result": 200,
"body": { "temp": 75, "humidity": 49 }
}