== 000000book API Docs

===== **BETA NOTICE** =====

The site is undergoing active development, and this documentation is incomplete. Pleaes email us if you have questions or run into problems. You can also join the new [[http://groups.google.com/group/graffiti-markup-language|GML mailing list]]

Contact us via email: [[mailto:info@000000book.com]]
Or hit us up on IRC: irc://irc.freenode.net/#fatlab

== What is Graffiti Markup Language (GML)? ==

Graffiti Markup Language is an XML-based format for representing the motion data of a graffiti writer (or other gestures)

GML is currently used to capture and replay the motion data from graffiti applications like [[http://graffitianalysis.com|Graffiti Analysis]], [[http://graffitiresearchlab.com|LASER Tag]] and the [[http://eyewriter.org|EyeWriter]] that have been developed by the Graffiti Research Lab/FAT Lab and openFrameworks teams.

An incomplete list of other applications using GML: http://000000book.com/apps

== Downloading GML ==

A GML document is composed of any number of 'drawings', which have 'strokes' composed of (x, y, time) tuples. 

The authoritative GML format spec is located at [[http://fffff.at/gml]]. See also: [[Minimum GML Requirements]]

000000book.com (blackbook) is meant as an open repository for GML data, and any application can upload & download GML from the site freely.

**Downloading GML:**
* every tag page contains a handy 'Download GML' button
* or simply append ".gml" to the URL of any Blackbook data page, e.g. <code>http://000000book.com/data/154.gml</code>
* you can also download in other formats -- .json includes the full GML as JSON, and .xml (for metadata-only) -- for more on JSON (GSON!) see [[Drawing with Javascript & JSON]]

**Other handy API access points**

* latest tag uploaded site-wide: <code>curl http://000000book.com/latest.gml</code>
* random tag: <code>curl http://000000book.com/random.gml</code>
* latest tag by user "tempt1" (TODO): <code>curl http://000000book.com/tempt1/latest.gml</code>
* latest from application "eyewriter" (TODO): <code>curl http://000000book.com/latest.gml?application=eyewriter</code>



== Ready & Drawing GML ==

* TODO! -- information about the time data, strokes, drawings, scaling/rotation, different fill/brush modes, etc.
=== Code: Drawing (Javascript, Flash, C++, Processing etc) ===

  * for a C++/openFrameworks example, see Graffiti Analysis: http://graffitianalysis.com/downloads/
  * for a Javascript example, see Canvasplayer: http://jamiedubs.com/canvasplayer
  * for an iPhone example, see source code downloads for DustTag http://graffitianalysis.com/iphone/
  * for a Flash example, see Ben Hopkins' http://kode80.com/2010/01/08/stylized-graffiti-rendering/
  * for a Processing example, see Golan Levin's [[http://fffff.at/gml-robotagger/|Robotagger]] GML->DXF converter: http://fffff.at/files/2010/01/GML_to_DXF-100109a.zip



== Uploading GML to 000000book.com ==

Sending your application's GML data to blackbook is simple, and authenticating or registering your app is optional

Send an HTTP POST request to **http://000000book.com/data** with a data payload containing:
  
* **GML** //(text)//* [the complete GML data, required; this will be validated for required GML fields, e.g. at least one x/y point; maximum functional size is approx. 1MB]
* **application** //(string)//* [the name of your application; required, should be unique]

**Optional Fields**

The following fields can be specified either in the GML *or* via HTTP POST to #000000book, which will write them into the GML for you.

* **keywords** //(string)// [comma-separated list of keywords ('tags', not to be confused w/ graf tags)]
* **location** //(string)// [name like 'NYC', lat/long coordinates, or even a URL]
* **username** //(string)// [a 000000book user's login]
* **author** //(string)// [the person who was actually writing]
* **uniqueKey** //(string)// [a unique device id for device pairing, e.g. iPhone UUID or computer MAC address] (*NOTE: currently *must* be in the GML, not accepted via POST)

The "uniqueKey" payload can also be provided in order to uniquely identify the uploading device, e.g. an iPhone. User's can later pair their 000000book account with a specified uniqueKey (see "Device Pairing" below).

=== Getting started with curl ===

If you are on Mac OS or Linux you can crack open a terminal and get started uploading GML just using `curl`:
 
<code>
curl -A curlwriter -d application=curlwriter&gml="<gml><pt><x>1</x><y>1</y><t>1</t></pt></gml>" http://000000book.com/data
</code>

  * -A = specify a user-agent
  * -d = the POST data to send -- just need 'application' & 'gml'



== Advanced Blackbook-Fu ==

* [[API Full Method list]]


=== Device Pairing ===

* TODO
* your application can include a <code>'uniqueKey'</pre> tag in its GML header that specifies an iPhone UUID, computer MAC address, etc. -- something to uniquely identify the device for later pairing with a user account.
* This uniqueKey will be parsed, SHA-1 hashed & stripped from public display to maintain user privacy
 

=== Application Registration & Embedding ===

* TODO
* you can register an application for listing -- 
* if your app is viewable in a web browser (e.g. Flash or javascript) you can specify the .swf or .js file and it can be used as a playback player on every tag page
* We've created the Vanderplayer (flash) and Canvasplayer (javascript) as demonstrations


=== User Authentication ===

* TODO
* user registration is optional.
* currently cannot authenticate through or with the API