web Requests

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

note

Caveats When Performing Web Requests:

  1. The Notecard must be in continuous mode and connected to Notehub to perform any of the requests below. For example:

    {
 "req": "hub.set",
 "product": "com.your-company.your-name:your_product",
 "mode": "continuous"
}

  2. The endpoint to the 3rd party API or service must be configured as a proxy Route in Notehub as a "Proxy for Device Web Requests" type.

  3. The Notecard can only accept valid JSON in response to a GET, POST, or PUT request unless you override the default content argument of application/json with the appropriate MIME type.

For more information on these requirements, see the Web Transactions Guide.

web.get

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 (Added in v1.5.6)

integer (optional)

If specified, overrides the default 90 second timeout.

async (Added in v5.1.1)

boolean (optional)

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

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

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

      web.post

      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 payloads with the Notecard.

      content

      string (optional)

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

      seconds (Added in v1.5.6)

      integer (optional)

      If specified, overrides the default 90 second timeout.

      total (Added in v3.2.1)

      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 (Added in v3.2.1)

      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 (Added in v3.2.1)

      string (optional)

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

      max (Added in v3.2.1)

      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 (Added in v3.2.1)

      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 (Added in v5.1.1)

      boolean (optional)

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

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

          Example Response
          {
  "result": 201
}

          web.put

          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 payloads with the Notecard.

          content

          string (optional)

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

          seconds (Added in v1.5.6)

          integer (optional)

          If specified, overrides the default 90 second timeout.

          total (Added in v3.2.1)

          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 (Added in v3.2.1)

          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 (Added in v3.2.1)

          string (optional)

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

          max (Added in v3.2.1)

          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 (Added in v3.2.1)

          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 (Added in v5.1.1)

          boolean (optional)

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

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

              Example Response
              {
  "result": 204
}

              web.delete (Added in v1.5.6)

              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 (Added in v1.5.6)

              integer (optional)

              If specified, overrides the default 90 second timeout.

              async (Added in v5.1.1)

              boolean (optional)

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

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

                  Example Response
                  {
  "result": 204
}
                  More information: