Pachube Client

Table of Contents

  1. Example
  2. Getting started
  3. Usage

This page describes the PachubeClient class which has been written as a wrapper around the HTTPClient class for Pachube updates.

Example

A sample program is given to show how Pachube updates can be made using the class as defined below. It is necessary to supply an API key for authentication purposes with the Pachube server, and specify the feed ID and comma separated values to be sent.

#include "mbed.h"

#include "EthernetNetIf.h"
#include "PachubeClient.h"

// pachube client
PachubeClient pachube("my API key");

// ethernet network interface for ip stack
EthernetNetIf eth;

int main() {

    // setup the network interface (by dhcp)
    eth.setup();

    pachube.PutCsv("my feed ID", "my values, comma separated");
    printf("Pachube result  / response : %d / %d\n", 
           pachube.Result(), pachube.Response());

}

Getting started

It will be necessary to create two files in the compiler as below; the class header (.h) and its definition (.cpp).

PachubeClient.h

PachubeClient.h

#ifndef PACHUBECLIENT_H_
#define PACHUBECLIENT_H_

#include <mbed.h>
#include <HTTPClient.h>

class PachubeClient {

public:
    // constructor and destructor
    PachubeClient(const string& apiKey);
    virtual ~PachubeClient();

    // put csv method to feed
    void PutCsv(const string& environmentID, const string& data);

    // put csv method to datastream
    void PutCsv(const string& environmentID, const string& datastreamID, const string& data);

    // http result and response
    HTTPResult Result();
    int Response();
            
private:
    // http client and data
    HTTPClient _client;
    HTTPText _csvContent;
    
    // http result and response
    HTTPResult _result;
    int _response;
    
};

#endif // PACHUBECLIENT_H_

PachubeClient.cpp

PachubeClient.cpp

#include "PachubeClient.h"

PachubeClient::PachubeClient(const string& apiKey) : _client(), _csvContent("text/csv") {
    _client.setRequestHeader("X-PachubeApiKey", apiKey);
}

PachubeClient::~PachubeClient() {
}

// put csv method to feed
void PachubeClient::PutCsv(const string& environmentID, const string& data) {
    _csvContent.set(data);
    string uri = "http://api.pachube.com/v1/feeds/" + environmentID + ".csv?_method=put";
    _result = _client.post(uri.c_str(), _csvContent, NULL);
    _response = _client.getHTTPResponseCode();
}

// put csv method to datastream
void PachubeClient::PutCsv(const string& environmentID, const string& datastreamID, const string& data) {
    _csvContent.set(data);
    string uri = "http://api.pachube.com/v1/feeds/" + environmentID + "/datastreams/" + datastreamID + ".csv?_method=put";
    _result = _client.post(uri.c_str(), _csvContent, NULL);
    _response = _client.getHTTPResponseCode();
}

// http result and response
HTTPResult PachubeClient::Result() {
    return _result;
}
int PachubeClient::Response() {
    return _response;
}

Usage

An initialised networking stack is required (see Working with the networking stack).

#include "EthernetNetIf.h"
EthernetNetIf eth; 
...
    eth.setup();

Constructor

In code, it is necessary to call the constructor with the API key that will be used for updates.

#include "PachubeClient.h"
...
    PachubeClient pachube("my API key");

Methods

After that, the PutCsv method can be called which has two signatures depending on whether a feed or datastream update is required.

// update feed (data is comma separated values)
void PachubeClient::PutCsv(const string& environmentID, const string& data)

// update datastream (data is single value)
void PachubeClient::PutCsv(const string& environmentID, const string& datastreamID, const string& data)

Parameters

After the PutCsv method is called, the following parameters can be read.

// http result
HttpResult Result()

// http response
int Response()

The Result() is the return value from the internal HTTPClient object. A value of HTTP_OK indicates a successful post to the server. The Response() is the http response code from the Pachube server. As detailed in the API documentation, these are as follows.

200 OK: request processed successfully.
401 Not Authorized: either you need to provide authentication credentials, 
    or the credentials provided aren't valid.
403 Forbidden: Pachube understands your request, but refuses to fulfill it.
    An accompanying error message should explain why.
404 Not Found: either you're requesting an invalid URI or the resource in 
    question doesn't exist (eg. no such feed). 
422 Unprocessable Entity: Pachube was unable to create a feed because the EEML 
   was not complete/valid (e.g. it didn't include a "title" element). 
500 Internal Server Error: Something went wrong... Please post to the forum 
    about it and we will investigate.
503 No server error: usually occurs when there are too many requests coming 
    into Pachube - if you get this from an /api request then the error message
    will be returned in XML in the response.
All wikipages