Skip to content

Latest commit

 

History

History
258 lines (193 loc) · 5.88 KB

README.md

File metadata and controls

258 lines (193 loc) · 5.88 KB
Raw

A practical and easy to use generic HTTP client library for the Yun

Features

  • GET/POST/PUT/DELETE
  • Both sync and async requests
  • You can access the HTTP response code and headers, not just the body
  • Basic authorization
  • Multiple extra request headers
  • Extraction of a particular response header value
  • Designed for efficiency and easy usage
  • Built on top of the Bridge library
  • Uses cURL on the Linux side

Examples

List the names and Ids of your Adafruit IO Feeds

#include <Bridge.h>
#include <BridgeHttpClient.h>

#include <ArduinoJson.h>

void setup() {
  pinMode(13, OUTPUT);
  digitalWrite(13, LOW);
  Bridge.begin(); // Initialize Bridge
  digitalWrite(13, HIGH);

  SerialUSB.begin(9600);
  while (!SerialUSB); // wait for the serial connection

  BridgeHttpClient client;

  // Add request headers
  // REPLACE THE XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX WITH YOUR AIO KEY!!!
  client.addHeader("X-AIO-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
  client.addHeader("Accept: application/json");

  // Using HTTPS and peer cert. will not be able to auth.
  client.enableInsecure();

  // Adafruit IO REST API call
  client.get("https://io.adafruit.com/api/feeds");

  // Collect the response body into this string for parsing
  String response;

  while (client.available() > 0) {
    char c = client.read();
    response += c;
  }

  // Parse the list of feeds and print the name and ids, limited to 4 feeds
  const int JSON_BUFFER = JSON_ARRAY_SIZE(4) + 4*JSON_OBJECT_SIZE(14);
  StaticJsonBuffer<JSON_BUFFER> jsonBuffer;

  JsonArray& array = jsonBuffer.parseArray(response);
  if (!array.success()) {
    SerialUSB.println("parseArray() failed");
    while (1) {}
  }

  // List the feed names and Ids
  SerialUSB.println("Your Adafruit IO Feed Name/Id listing:");
  for (JsonArray::iterator it=array.begin(); it!=array.end(); ++it) {
    JsonObject& feed = it->as<JsonObject&>();
    feed["name"].printTo(SerialUSB);
    SerialUSB.print("/");
    feed["id"].printTo(SerialUSB);
    SerialUSB.println();
  }
}

void loop() {
  // Do nothing
}

Asynchronous POST example

#include <Bridge.h>
#include <BridgeHttpClient.h>

BridgeHttpClient client;

void setup() {
  pinMode(13, OUTPUT);
  digitalWrite(13, LOW);
  Bridge.begin(); // Initialize Bridge
  digitalWrite(13, HIGH);

  SerialUSB.begin(9600);
  while (!SerialUSB); // wait for a serial connection

  client.addHeader("X-Api-Key: 12345");
  client.addHeader("Accept: application/json");
  client.addHeader("Content-Type: application/json");

  client.enableInsecure(); // Using HTTPS and peer cert. will not be able to auth.

  String data = "{\"sensorData\":\"";
  data += 123;
  data += "\"}";
  client.postAsync("https://httpbin.org/post", data);
  SerialUSB.print("Sending request");
}

void loop() {

  if (client.finished()) {

    SerialUSB.println();
    SerialUSB.println("Response Body:");
    while (client.available() > 0) {
      char c = client.read();
      SerialUSB.print(c);
    }

    SerialUSB.print("Response Code: ");
    SerialUSB.println(client.getResponseCode());

    while (1) {} // stop

  } else {
    // not finished yet, wait and retry
    SerialUSB.print(".");
    delay(100);
  }
}

Usage

First instantiate a client

BridgeHttpClient client;

Adding Basic Auth. to your request (optional)

client.basicAuth("user", "password");

Adding extra request headers to your request (optional)

client.addHeader("X-Api-Key: 12345");
client.addHeader("Accept: application/json");
client.addHeader("Content-Type: application/json");

Note: The library supports up to 16 extra user addable request headers.

When issuing HTTPS requests consider this

If your HTTPS request fails due to the "certificate cannot be authenticated with known CA certificates" problem, you can circumvent the issue by calling the following method before the request.

client.enableInsecure();

Synchronous requests

// HTTP GET, call won't return until finished
client.get("https://httpbin.org/headers");

// HTTP POST a JSON payload, call won't return until finished
String data = "{\"sensorData\":\"";
data += 123;
data += "\"}";
client.post("https://httpbin.org/post", data);

Asynchronous requests

To check whether the async request has completed or not, you can use the following method from the parent class.

// HTTP GET, call returns before completion.
client.getAsync("https://httpbin.org/headers");
// ...
// Later you can check whether the call has finished
if (client.finished()) {
  // Request has finished
}

Exit status of the client

After the sync or async request has finished, you can check the exit status of the client like this.

if (client.exitValue() == 0) {
  // Success, continue processing
} else {
  // Error
}

HTTP response code

If you need the HTTP response code for your application, use the following method.

if (client.getResponseCode() == 200) {
  // HTTP OK
}

HTTP response headers

To access all the received HTTP response headers, you can use this method.

String responseHeaders = getResponseHeaders();
// Process response headers by yourself

Note: It returns all the headers in one string object. This is useful if you want to process the headers by yourself. If you're interested in a particular header value only, use the next method instead!

HTTP response header value

String server;
if (client.getResponseHeaderValue("Server", server)) {
  SerialUSB.print("Header \"Server\" has value: ");
  SerialUSB.println(server);
} else {
  SerialUSB.println("Header \"Server\" not found");
}

HTTP response body

SerialUSB.println("Response Body:");
while (client.available() > 0) {
  char c = client.read();
  SerialUSB.print(c);
}

TODO

  • Add proxy support
  • Provide better description
  • Create useful examples