--- title: web Requests - API Reference description: Notecard can perform requests and obtain responses from 3rd-party APIs and services with the web API requests. source_url: https://dev.blues.io/api-reference/notecard-api/web-requests/ canonical_url: https://dev.blues.io/api-reference/notecard-api/web-requests/ markdown_url: https://dev.blues.io/api-reference/notecard-api/web-requests.md --- # web Requests The Notecard can perform requests and obtain responses from 3rd-party APIs and services with the `web` API requests. ## web Supported on (Cell, Cell+WiFi, Skylo, WiFi) 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`](https://dev.blues.io/api-reference/notecard-api/web-requests/latest.md#web-get), [`POST`](https://dev.blues.io/api-reference/notecard-api/web-requests/latest.md#web-post), [`PUT`](https://dev.blues.io/api-reference/notecard-api/web-requests/latest.md#web-put), and [`DELETE`](https://dev.blues.io/api-reference/notecard-api/web-requests/latest.md#web-delete) requests in the documentation provided. > **Warning:** > > The Notecard must have an active connection to Notehub while performing any web.\* request. Please [consult this guide](https://dev.blues.io/notecard/notecard-walkthrough/web-transactions.md) for more information. Arguments ### `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. `"CONNECT"`: Establishes a tunnel to the server identified by the target resource. `"DELETE"`: Performs a simple HTTP or HTTPS `DELETE` request against an external endpoint, and returns the response to the Notecard. `"GET"`: Performs a simple HTTP or HTTPS `GET` request against an external endpoint, and returns the response to the Notecard. `"HEAD"`: Requests the headers that would be returned if the URL was requested with a `GET` method. `"OPTIONS"`: Requests the communication options available for the target resource. `"PATCH"`: Applies partial modifications to a resource at the target endpoint. `"POST"`: Performs a simple HTTP or HTTPS `POST` request against an external endpoint, and returns the response to the Notecard. `"PUT"`: Performs a simple HTTP or HTTPS `PUT` request against an external endpoint, and returns the response to the Notecard. `"TRACE"`: Performs a message loop-back test along the path to the target resource. ### `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. **Example** **JSON** ```json { "req": "web", "method": "GET", "route": "weatherInfo", "name": "/getLatest" } ``` **C/C++** ```cpp J *req = NoteNewRequest("web"); JAddStringToObject(req, "method", "GET"); JAddStringToObject(req, "route", "weatherInfo"); JAddStringToObject(req, "name", "/getLatest"); NoteRequest(req); ``` **Python** ```python 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 Example Response ```json { "result": 200, "body": { "temp": 75, "humidity": 49 } } ``` ## web.delete Supported on (Cell, Cell+WiFi, Skylo, WiFi) Performs a simple HTTP or HTTPS `DELETE` request against an external endpoint, and returns the response to the Notecard. Arguments ### `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. This argument only applies when the Notecard is in `continuous` mode and currently online. ### `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 a local-only Database Notefile (.dbx) where the response will be stored when the web request is executed as a queued web transaction (e.g. if the request is made when Notecard is not in continuous mode and not online). If `file` is not specified, queued web transaction responses are discarded. This argument is not used when the Notecard is in `continuous` mode and online, as responses in that case are returned directly to the host. ### `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 within the local-only Database Notefile (.dbx) specified by the `file` argument (see above). Used with queued web transactions to identify a specific Note where the response will be stored. ### `route` *string* Alias for a Proxy Route in Notehub. ### `seconds` *integer (optional, default `90`)* If specified, overrides the default 90 second timeout. **Example** **JSON** ```json { "req": "web.delete", "route": "SensorService", "name": "/deleteReading?id=1" } ``` **C/C++** ```cpp J *req = NoteNewRequest("web.delete"); JAddStringToObject(req, "route", "SensorService"); JAddStringToObject(req, "name", "/deleteReading?id=1"); NoteRequest(req); ``` **Python** ```python 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. Example Response ```json { "result": 204 } ``` ## web.get Supported on (Cell, Cell+WiFi, Skylo, WiFi) Performs a simple HTTP or HTTPS `GET` request against an external endpoint, and returns the response to the Notecard. Arguments ### `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](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md). ### `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 a local-only Database Notefile (.dbx) where the response will be stored when the web request is executed as a queued web transaction (e.g. if the request is made when Notecard is not in continuous mode and not online). If `file` is not specified, queued web transaction responses are discarded. This argument is not used when the Notecard is in `continuous` mode and online, as responses in that case are returned directly to the host. ### `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 within the local-only Database Notefile (.dbx) specified by the `file` argument (see above). Used with queued web transactions to identify a specific Note where the response will be stored. ### `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. **Example** **JSON** ```json { "req": "web.get", "route": "weatherInfo", "name": "/getLatest" } ``` **C/C++** ```cpp J *req = NoteNewRequest("web.get"); JAddStringToObject(req, "route", "weatherInfo"); JAddStringToObject(req, "name", "/getLatest"); NoteRequest(req); ``` **Python** ```python 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. Example Response ```json { "result": 200, "body": { "temp": 75, "humidity": 49 } } ``` ## web.post Supported on (Cell, Cell+WiFi, Skylo, WiFi) Performs a simple HTTP or HTTPS `POST` request against an external endpoint, and returns the response to the Notecard. Arguments ### `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. This argument only applies when the Notecard is in `continuous` mode and currently online. ### `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](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md). ### `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 a local-only Database Notefile (.dbx) where the response will be stored when the web request is executed as a queued web transaction (e.g. if the request is made when Notecard is not in continuous mode and not online). If `file` is not specified, queued web transaction responses are discarded. This argument is not used when the Notecard is in `continuous` mode and online, as responses in that case are returned directly to the host. ### `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 within the local-only Database Notefile (.dbx) specified by the `file` argument (see above). Used with queued web transactions to identify a specific Note where the response will be stored. ### `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](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md#binary-uploads-with-web-apis) 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 using the `application/octet-stream` content type, you may send large payloads to Notehub in fragments spanning several `web.post` requests by using `offset` (see above) and `total`. The `total` field indicates the total size, in bytes, of the 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. **Example** **JSON** ```json { "req": "web.post", "route": "SensorService", "name": "/addReading", "body": { "temp": 72.32, "humidity": 32.2 } } ``` **C/C++** ```cpp J *req = NoteNewRequest("web.post"); JAddStringToObject(req, "route", "SensorService"); JAddStringToObject(req, "name", "/addReading"); J *body = JAddObjectToObject(req, "body"); JAddNumberToObject(body, "temp", 72.32); JAddNumberToObject(body, "humidity", 32.2); NoteRequest(req); ``` **Python** ```python req = {"req": "web.post"} req["route"] = "SensorService" req["name"] = "/addReading" req["body"] = {"temp": 72.32, "humidity": 32.2} 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. Example Response ```json { "result": 201 } ``` ## web.put Supported on (Cell, Cell+WiFi, Skylo, WiFi) Performs a simple HTTP or HTTPS `PUT` request against an external endpoint, and returns the response to the Notecard. Arguments ### `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. This argument only applies when the Notecard is in `continuous` mode and currently online. ### `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](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md). ### `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 a local-only Database Notefile (.dbx) where the response will be stored when the web request is executed as a queued web transaction (e.g. if the request is made when Notecard is not in continuous mode and not online). If `file` is not specified, queued web transaction responses are discarded. This argument is not used when the Notecard is in `continuous` mode and online, as responses in that case are returned directly to the host. ### `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 within the local-only Database Notefile (.dbx) specified by the `file` argument (see above). Used with queued web transactions to identify a specific Note where the response will be stored. ### `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](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md#binary-uploads-with-web-apis) 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 using the `application/octet-stream` content type, you may send large payloads to Notehub in fragments spanning several `web.put` requests by using `offset` (see above) and `total`. The `total` field indicates the total size, in bytes, of the 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. **Example** **JSON** ```json { "req": "web.put", "route": "SensorService", "name": "/updateReading", "body": { "id": 1234, "temp": 72.32, "humidity": 32.2 } } ``` **C/C++** ```cpp J *req = NoteNewRequest("web.put"); JAddStringToObject(req, "route", "SensorService"); JAddStringToObject(req, "name", "/updateReading"); J *body = JAddObjectToObject(req, "body"); JAddNumberToObject(body, "id", 1234); JAddNumberToObject(body, "temp", 72.32); JAddNumberToObject(body, "humidity", 32.2); NoteRequest(req); ``` **Python** ```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) ``` 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. Example Response ```json { "result": 204 } ``` [var Requests](https://dev.blues.io/api-reference/notecard-api/var-requests.md "var Requests")