Permalink
Browse files

port the rest of the docs

  • Loading branch information...
1 parent 93a063f commit 4973c291baac9e1fe5d864fea2d687d4e2004140 @qrush qrush committed May 22, 2012
Showing with 286 additions and 0 deletions.
  1. +73 −0 sections/data_reference.md
  2. +29 −0 sections/search.md
  3. +90 −0 sections/streaming.md
  4. +52 −0 sections/transcripts.md
  5. +42 −0 sections/users.md
View
@@ -0,0 +1,73 @@
+Data Reference
+==============
+
+The following sections describe the different data types used by the Campfire API.
+
+Message
+-------
+
+``` xml
+<message>
+ <id type="integer">1</id>
+ <room-id type="integer">1</room-id>
+ <user-id type="integer">2</user-id>
+ <body>Hello Room</body>
+ <created-at type="datetime">2009-11-22T23:46:58Z</created-at>
+ <type>#{TextMessage || PasteMessage || SoundMessage || AdvertisementMessage ||
+ AllowGuestsMessage || DisallowGuestsMessage || IdleMessage || KickMessage ||
+ LeaveMessage || SystemMessage || TimestampMessage || TopicChangeMessage ||
+ UnidleMessage || UnlockMessage || UploadMessage}</type>
+ <starred>true</starred>
+</message>
+```
+
+Room
+----
+
+``` xml
+<room>
+ <id type="integer">1</id>
+ <name>North May St.</name>
+ <topic>37signals HQ</topic>
+ <membership-limit type="integer">60</membership-limit>
+ <full type="boolean">false</full>
+ <open-to-guests type="boolean">true</open-to-guests>
+ <active-token-value>#{ 4c8fb -- requires open-to-guests is true}</active-token-value>
+ <updated-at type="datetime">2009-11-17T19:41:38Z</updated-at>
+ <created-at type="datetime">2009-11-17T19:41:38Z</created-at>
+ <users type="array">
+ ...
+ </users>
+</room>
+```
+
+Upload
+------
+
+``` xml
+<upload>
+ <id type="integer">1</id>
+ <name>picture.jpg</name>
+ <room-id type="integer">1</room-id>
+ <user-id type="integer">1</user-id>
+ <byte-size type="integer">10063</byte-size>
+ <content-type>image/jpeg</content-type>
+ <full-url>https://account.campfirenow.com/room/1/uploads/1/picture.jpg</full-url>
+ <created-at type="datetime">2009-11-20T23:25:14Z</created-at>
+</upload>
+```
+
+User
+----
+
+``` xml
+<user>
+ <id type="integer">1</id>
+ <name>Jason Fried</name>
+ <email-address>jason@37signals.com</email-address>
+ <admin type="boolean">#{true || false}</admin>
+ <created-at type="datetime">2009-11-20T16:41:39Z</created-at>
+ <type>#{Member || Guest}</type>
+ <avatar-url>https://asset0.37img.com/global/.../avatar.png</avatar-url>
+</user>
+```
View
@@ -0,0 +1,29 @@
+Search
+======
+
+Looks through transcripts on this accounts.
+
+For the full XML representation of messages, [check out the data reference](https://github.com/37signals/basecamp-classic-api/blob/master/sections/data_reference.md#message).
+
+
+Search for term
+---------------
+
+* `GET /search/#{term}.xml` returns all the messages across all rooms on this account containing the supplied term.
+
+**Response:**
+
+``` xml
+<messages type="array">
+ <message>
+ <id type="integer">1</id>
+ <body>Hello</body>
+ <room-id type="integer">1</room-id>
+ <user-id type="integer">2</user-id>
+ <created-at type="datetime">2009-11-22T19:11:41Z</created-at>
+ <type>TextMessage</type>
+ <starred>true</starred>
+ </message>
+ ...
+</messages>
+```
View
@@ -0,0 +1,90 @@
+Streaming
+=========
+
+The Streaming API allows you to monitor a room in real time. The authenticated user must already have joined the room in order to use this API.
+
+
+Connections
+-----------
+
+Our servers will try to hold the streaming connections open indefinitely. However, API clients must be able to handle occasional timeouts or disruptions. Upon unexpected disconnection, API clients should wait for a few seconds before trying to reconnect.
+
+
+Formats
+-------
+
+The data stream is available in JSON or XML format. JSON is recommended.
+
+
+API
+---
+
+* `GET https://streaming.campfirenow.com/room/#{id}/live.json` stream a single room’s messages.
+
+The target host is always `streaming.campfirenow.com`.
+
+**Response:**
+
+``` json
+{"room_id":1,"created_at":"2009-12-01 23:44:40","body":"hello","id":1,
+ "user_id":1,"type":"TextMessage","starred":"true"}
+{"room_id":1,"created_at":"2009-12-01 23:40:00","body":null,"id":2,
+ "user_id":null,"type":"TimestampMessage","starred":"false"}
+...
+```
+
+
+Examples
+--------
+
+Need to get started quickly with the Campfire Streaming API? Try one of our example scripts that use the [twitter-stream](http://github.com/voloko/twitter-stream) library or [YAJL Ruby C bindings](http://github.com/brianmario/yajl-ruby):
+
+**twitter-stream**
+
+``` ruby
+# gem install twitter-stream
+require 'twitter/json_stream'
+
+token = 'xxx' # your API token
+room_id = 111 # the ID of the room you want to stream
+
+options = {
+ :path => "/room/#{room_id}/live.json",
+ :host => 'streaming.campfirenow.com',
+ :auth => "#{token}:x"
+}
+
+EventMachine::run do
+ stream = Twitter::JSONStream.connect(options)
+
+ stream.each_item do |item|
+ puts item
+ end
+
+ stream.on_error do |message|
+ puts "ERROR:#{message.inspect}"
+ end
+
+ stream.on_max_reconnects do |timeout, retries|
+ puts "Tried #{retries} times to connect."
+ exit
+ end
+end
+```
+
+**YAJL**
+
+``` ruby
+# gem install yajl-ruby
+
+require "uri"
+require "yajl/http_stream"
+
+token = 'xxx' # your API token
+room_id = 111 # the ID of the room you want to stream
+
+url = URI.parse("http://#{token}:x@streaming.campfirenow.com//room/#{room_id}/live.json")
+Yajl::HttpStream.get(url) do |message|
+ puts message.inspect
+end
+```
View
@@ -0,0 +1,52 @@
+Transcripts
+===========
+
+The Transcripts API lets you fetch all the messages for a specific day.
+
+For the full XML representation of messages, [check out the data reference](https://github.com/37signals/basecamp-classic-api/blob/master/sections/data_reference.md#message).
+
+
+Get messages for today
+----------------------
+
+* `GET /room/#{id}/transcript.xml` returns all the messages sent today to a room.
+
+**Response:**
+
+``` xml
+<messages type="array">
+ <message>
+ <id type="integer">1</id>
+ <body>Hello</body>
+ <room-id type="integer">1</room-id>
+ <user-id type="integer">2</user-id>
+ <created-at type="datetime">2009-11-22T19:11:41Z</created-at>
+ <type>TextMessage</type>
+ <starred>false</starred>
+ </message>
+ ...
+</messages>
+```
+
+
+Get messages for a specific date
+--------------------------------
+
+* `GET /room/#{id}/transcript/#{year}/#{month}/#{day}.xml` returns all the messages sent on a specific date to a room.
+
+**Response:**
+
+``` xml
+<messages type="array">
+ <message>
+ <id type="integer">1</id>
+ <body>Hello</body>
+ <room-id type="integer">1</room-id>
+ <user-id type="integer">2</user-id>
+ <created-at type="datetime">2009-11-22T19:11:41Z</created-at>
+ <type>TextMessage</type>
+ <starred>false</type>
+ </message>
+ ...
+</messages>
+```
View
@@ -0,0 +1,42 @@
+Users
+=====
+
+Get user
+--------
+
+* `GET /users/#{id}.xml` returns an existing user.
+
+**Response:**
+
+``` xml
+<user>
+ <id type="integer">1</id>
+ <name>Jason Fried</name>
+ <email-address>jason@37signals.com</email-address>
+ <admin type="boolean">true</admin>
+ <created-at type="datetime">2009-11-20T16:41:39Z</created-at>
+ <type>Member</type>
+ <avatar-url>https://asset0.37img.com/global/.../avatar.png</avatar-url>
+</user>
+```
+
+Get self
+--------
+
+* `GET /users/me.xml` returns the user making the API request.
+
+This end-point may be requested using the username and password, rather than the API token. This makes it easier for applications to obtain the typically-obscure API token on mobile platforms, where it is inconvenient to have to key in all 40 characters of the token.
+
+**Response:**
+
+``` xml
+<user>
+ <id type="integer">1</id>
+ <name>Jason Fried</name>
+ <email-address>jason@37signals.com</email-address>
+ <admin type="boolean">true</admin>
+ <created-at type="datetime">2009-11-20T16:41:39Z</created-at>
+ <type>Member</type>
+ <avatar-url>https://asset0.37img.com/global/.../avatar.png</avatar-url>
+</user>
+```

0 comments on commit 4973c29

Please sign in to comment.