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.

`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

JSON

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

`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.

Example Response

JSON

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

`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

JSON

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

`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

JSON

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

JSON

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

var Requests