API

From Noisebridge
(Difference between revisions)
Jump to: navigation, search
(8 intermediate revisions by one user not shown)
Line 15: Line 15:
 
For instance, to open the door using curl:
 
For instance, to open the door using curl:
  
<tt>bash     curl -X POST -d open=True http://api.noisebridge.net/gate/</tt>
+
     curl -X POST -d open=True http://api.noisebridge.net/gate/</source>
 
+
 
=== GET /hello/[name] ===
 
=== GET /hello/[name] ===
  
Line 29: Line 28:
 
Gets interesting stats about the gate. Currently:
 
Gets interesting stats about the gate. Currently:
  
<tt>json     {    ringing: boolean    }</tt>
+
<pre class="json">    {
 
+
     ringing: boolean
 +
     }</pre>
 
Where 'ringing' is true if the gate buzzer is ringing at that moment, or in the last few seconds, as users may push the button for a very short time. The amount of time that this state is cached is totally up to the Gateman daemon that runs to interact with the gate hardware.
 
Where 'ringing' is true if the gate buzzer is ringing at that moment, or in the last few seconds, as users may push the button for a very short time. The amount of time that this state is cached is totally up to the Gateman daemon that runs to interact with the gate hardware.
  
Line 37: Line 37:
 
With open=True, opens the door. Returns a 300 error if unsuccessful, and the following additions to the /gate/ stats if successful:
 
With open=True, opens the door. Returns a 300 error if unsuccessful, and the following additions to the /gate/ stats if successful:
  
<tt>json     {    open : True    message: string    }</tt>
+
<pre class="json">    {
 +
     open : True
 +
     message: string
 +
     }</pre>
 +
With key=XXXX, will optionally check the key against the door code list.
 +
 
 +
Note that this isn't a required field. Currently if you omit the key field, the door will always open. It's intended to optionally allow other apps to offer the same door code authentication that we use for the phone booth entry.
 +
 
 +
=== POST /gate/key/[doorcode] ===
 +
 
 +
With create=True and an existing, valid doorcode, redirects to a URL of the form /gate/key/[newdoorcode] which gives a valid new doorcode to open the door.
 +
 
 +
With preferred=[number] you can suggest a doorcode you'd like to use. It's not guaranteed that the preferred option will be returned.
 +
 
 +
Requires comment=[contact email address for new number]
 +
 
 +
Suppose you have a doorcode 8499146, and you'd like to give a friend a new doorcode. She asks if she can have the number '7895473'
 +
 
 +
<pre lang="bash">curl -v -X POST -d create=True -d preferred=7895473 -d comment=&quot;I'm Dara, my email is newperson@example.com&quot; http://localhost:8080/gate/key/8499146</pre>
 +
would return something like this:
 +
<pre>&gt; POST /gate/key/8499146 HTTP/1.1
 +
&gt; User-Agent: curl/7.26.0
 +
&gt; Host: localhost:8080
 +
&gt; Accept: */*
 +
&gt; Content-Length: 29
 +
&gt; Content-Type: application/x-www-form-urlencoded
 +
&gt;  * upload completely sent off: 29 out of 29 bytes * additional stuff not fine transfer.c:1037: 0 0 * HTTP 1.0, assume close after body
 +
&lt; HTTP/1.0 303 See Other
 +
&lt; Date: Mon, 05 Nov 2012 05:07:29 GMT
 +
&lt; localhost - - [04/Nov/2012 21:07:29] &quot;POST /gate/key/8499146 HTTP/1.1&quot; 303 0 Server: WSGIServer/0.1 Python/2.7.3rc2
 +
&lt; Content-Length: 0
 +
&lt; Content-Type: text/html; charset=UTF-8
 +
&lt; Location: http://localhost:8080/gate/key/7895473
 +
&lt;  * Closing connection #0</pre>
 +
 
 +
The Location header contains the new doorcode.
 +
 
 +
=== POST /audio/ ===
 +
 
 +
With say=[TEXT] will convert the TEXT into speech, and announce it to the space.
  
 
== Adding to the API ==
 
== Adding to the API ==
Line 45: Line 84:
 
Just add a function of the form:
 
Just add a function of the form:
  
<tt>python @api_app.route(&quot;/myurl/&quot;) def myfunc()    do_something_in_the_space()    return { 'success' : True, 'OMG IT WORXORRED' }</tt>
+
<pre lang="python">@api_app.route(&quot;/myurl/&quot;)
 
+
def myfunc()
 +
     do_something_in_the_space()
 +
     return { 'success' : True, 'OMG IT WORXORRED' }</pre>
 
== Deploying your new API ==
 
== Deploying your new API ==
  
You'll need sudo powers on pony. Check out the code using git:
+
You'll need sudo powers on minotaur. Check out the code using git:
 
+
<tt>bash    git clone /var/local/noise_api/</tt>
+
  
 +
<pre lang="bash">    git clone git@github.com:noisebridge/noise-api.git</pre>
 
Make your changes, and test them locally using
 
Make your changes, and test them locally using
  
<tt>bash     python api.py --debug</tt>
+
<pre lang="bash">  python api.py --debug</pre>
 +
When you're ready to deploy, change the Debian changelog in debian/changelog (the [http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.man.git.dch.html git-dch] program can help with this), and commit the code to the github repository..
  
When you're ready to deploy, commit the code, then pull it out to the runningversion of api.py.
+
Log onto minotaur, clone the git repository, and make a Debian package. Install it using dpkg -i
  
<tt>bash     cd /var/local/noise_api/     sudo git pull [your cloned directory goes here]     sudo make install</tt>
+
<pre lang="bash">  git clone git://github.com/noisebridge/noise-api.git
 +
  cd noise-api
 +
  make package
 +
  sudo dpkg -i ../noisebridge-api_0[whatever the version number is]*.deb
 +
</pre>

Revision as of 21:07, 1 January 2013

Contents

API for Noisebridge

This is a very simple Python WSGI App that provides a RESTful API for fun things in the Noisebridge space.

In the Noisebridge tradition, it's not stable! It will, however try to break in as noisy a way as possible if things change.

Using the API

The API is currently only available within the space. Once we have authorisation running, this will change.

The API is RESTful, and can be called at the URL:

http://api.noisebridge.net/[call]

For instance, to open the door using curl:

   curl -X POST -d open=True http://api.noisebridge.net/gate/</source>

GET /hello/[name]

Returns 'hello [name]'

GET /spaceapi/

Returns Noisebridge status, formatted as per http://hackerspaces.nl/spaceapi/

GET /gate/

Gets interesting stats about the gate. Currently:

    {
    ringing: boolean
    }

Where 'ringing' is true if the gate buzzer is ringing at that moment, or in the last few seconds, as users may push the button for a very short time. The amount of time that this state is cached is totally up to the Gateman daemon that runs to interact with the gate hardware.

POST /gate/

With open=True, opens the door. Returns a 300 error if unsuccessful, and the following additions to the /gate/ stats if successful:

    {
    open : True
    message: string
    }

With key=XXXX, will optionally check the key against the door code list.

Note that this isn't a required field. Currently if you omit the key field, the door will always open. It's intended to optionally allow other apps to offer the same door code authentication that we use for the phone booth entry.

POST /gate/key/[doorcode]

With create=True and an existing, valid doorcode, redirects to a URL of the form /gate/key/[newdoorcode] which gives a valid new doorcode to open the door.

With preferred=[number] you can suggest a doorcode you'd like to use. It's not guaranteed that the preferred option will be returned.

Requires comment=[contact email address for new number]

Suppose you have a doorcode 8499146, and you'd like to give a friend a new doorcode. She asks if she can have the number '7895473'

curl -v -X POST -d create=True -d preferred=7895473 -d comment="I'm Dara, my email is newperson@example.com" http://localhost:8080/gate/key/8499146

would return something like this:

> POST /gate/key/8499146 HTTP/1.1 
> User-Agent: curl/7.26.0 
> Host: localhost:8080 
> Accept: */* 
> Content-Length: 29 
> Content-Type: application/x-www-form-urlencoded 
>  * upload completely sent off: 29 out of 29 bytes * additional stuff not fine transfer.c:1037: 0 0 * HTTP 1.0, assume close after body 
< HTTP/1.0 303 See Other 
< Date: Mon, 05 Nov 2012 05:07:29 GMT 
< localhost - - [04/Nov/2012 21:07:29] "POST /gate/key/8499146 HTTP/1.1" 303 0 Server: WSGIServer/0.1 Python/2.7.3rc2 
< Content-Length: 0 
< Content-Type: text/html; charset=UTF-8 
< Location: http://localhost:8080/gate/key/7895473 
<  * Closing connection #0

The Location header contains the new doorcode.

POST /audio/

With say=[TEXT] will convert the TEXT into speech, and announce it to the space.

Adding to the API

api.py is a Bottle. It should be pretty self explanatory, even if you don't know much Python.

Just add a function of the form:

@api_app.route("/myurl/")
def myfunc()
    do_something_in_the_space()
    return { 'success' : True, 'OMG IT WORXORRED' }

Deploying your new API

You'll need sudo powers on minotaur. Check out the code using git:

    git clone git@github.com:noisebridge/noise-api.git

Make your changes, and test them locally using

   python api.py --debug

When you're ready to deploy, change the Debian changelog in debian/changelog (the git-dch program can help with this), and commit the code to the github repository..

Log onto minotaur, clone the git repository, and make a Debian package. Install it using dpkg -i

   git clone git://github.com/noisebridge/noise-api.git
   cd noise-api
   make package
   sudo dpkg -i ../noisebridge-api_0[whatever the version number is]*.deb
Personal tools