Page 1 of 1

restful api?

Posted: Sun Jun 08, 2014 2:49 pm
by kd8bxp
Where can I find documentation for the restful api?

Re: restful api?

Posted: Sun Jun 08, 2014 11:37 pm
by xobxob
Right now there's no formal documentation, but here's a quick version.

XOBXOB implements Create, Read, Update, and Delete for XOB's associated with your account. Each of these requests must be accompanied by your APIKey which you can find on your dashboard when you log in. The APIKey is included as a header field of the name APIKey.

The requests are all sent to

The requests are:


POST /v1/xobs/xob_name?message=value

where xob_name is the name of your XOB and message=value are the messages. You can list multiple message=value pairs separated by ampersands (just like any query string). If no XOB exists by the given name, one will be created.


GET /v1/xobs/xob_name

where xob_name is the name of your XOB. Currently, this will return all messages in your XOB along with one or two other fields with owner, etc. The extra fields may be eliminated soon in an update.


PUT /v1/xobs/xob_name?message=value

This is the same as POST except that a XOB will not be created if it doesn't already exist.


DELETE /v1/xobs/xob_name

This will delete the named XOB. Be careful, there's no undo!

So, there it is in a nutshell. Let me know if you have any other questions or feedback.

Re: restful api?

Posted: Mon Jun 09, 2014 9:13 pm
by kd8bxp
Excellent, the api is very easy to use., Thank you!

So you probably can tell, I am pretty new to XOBXOB - and I get what "switch" does, but how does "vaule" and "text" work?

Here is what I want to do, if I can do it with XOBXOB.
I want to setup an arduino to send me a tempature when I ask for it using the API.
I am going to use my computer to run a shell script, and ask for the tempature.
I'm guessing that would have to be done using either the vaule, or the text field, if you could/would explain those fields a little more it might help me out.

Thanks again,
I just came across XOBXOB a couple of days ago, and so far I am really enjoying the easy of use, and the API makes it even better.

Re: restful api?

Posted: Tue Jun 10, 2014 2:40 am
by xobxob

So, a XOB can hold a number of messages, each of which has a value. The name of the message and the values are arbitrary (with some constraints). When you create an account, your first XOB is created for you. Right now, it's called "XOB" which is a little confusing. I hope to release an update soon that changes that.

In any case, the first XOB also has three messages automatically created in it: text, value, and switch. That's so the sample sketches work and simple dashboard work a little better.

But, there's no reason you can't create a XOB yourself (from the advanced dashboard or from the API). You can use your own name for the XOB (e.g. "project1") and you can use arbitrary messages to match the application you're trying to create (e.g. you might want to use "temp" for your temperature reading). It's useful to note that no matter what the message is called, the content of the message is always a string. So, even though the default XOB has a message called "value", the value is represented as a string. That means that you have to convert the temperature into a string before you store it in a XOB and convert it from a string back to a value if you want to do calculations later. But, that's relatively easy.

BTW, instead of having to ask your Arduino to upload the temperature, it might be just as easy to have the Arduino upload the temperature every 10 seconds, or something. Each new temperature will overwrite the previous value. Then, whenever you want, you can get the current value from the XOB.

Anyway, I hope that helps. Let me know if you have any other questions.

Re: restful api?

Posted: Tue Jun 10, 2014 12:51 pm
by kd8bxp
Ok, thanks again, I had thought that was what was going on, but it's always better to ask just to be sure.

As far as the sending the tempature every 10 seconds or so.... Yes I thought about that, but ultimatly I want to add other sensor inputs as well, and make a mini-weather station. The thing is (and I know it's not a lot of data at this point), but if it sends information every 10 seconds or so, 3 things come to mine doing that. It will use resources that don't need to be used up both on the arduino and in the xobxob (again, knowing it's not a lot of data at this point). And second, the information could be a few seconds old - in my case that probably wouldn't matter. Third, as tempatures (humiditys/BP/etc) don't change much at least not quickly (in a weather station type situation) it would seem that again I would be using resources that don't really need to be used.

If on my computer the shell script I run askeds for what I want, each time, then I think I'm going to get fresher data (not that it really maters for what I'm doing), and not use as many resources. I have a "Beta-Bright" moving message sign hooked up to that computer, and I can take the "weather" information phase it into a message the sign understands and display "real-time" weather. OK I know I'm a nut but it's fun to do stuff like that, Got the sign in the living room, and people always want to know where I got it from and what I'm doing to make display tweets and other useless factoids,
So even my project is a little silly :-)

The Arduino can just sit and wait for "send temp" "send humidy" "send BP" and go into the correct sub-routine to do that, go back and wait some more.

I figured I'd start small thou, getting the tempature sensor working, and build up from there, at some point I'd like to add wind speed, but haven't gotten a wind speed detector to work yet, still working on that one :-)

As with everything "programming" wise I have found there are a dozen different ways to do something, and you get the same results.

Re: restful api?

Posted: Tue Jun 10, 2014 2:08 pm
by xobxob
You've raised some interesting points.

Regarding timing, XOBXOB currently only implements polling. So, the Arduino will have to poll XOBXOB periodically to see if anyone has asked for anything. Also, the display will have to poll to see if anything has been returned. You'd also have to add some communication mechanism to make sure the number coming back from a XOB was the current one, and not the previous one. This can add programming complexity and a bit of time to the request. On the other hand, if you upload the data periodically, communication would be easier (simple gets and posts), you'd know the current reading was relatively recent (depending on your polling frequency) and average delay would probably be shorter.

But, you're absolutely right about different ways to solve a problem. And, there are always multiple criteria to consider in determining the optimal solution.

Anyway, this sounds like an awesome project! Keep us posted.