| CARVIEW |
Sections
- Introduction
- Rooms
- Search
- Speak
- Transcripts
- Users
- Streaming
- Data Reference
API Mailing List
Share thoughts, ask questions, and help fellow developers on the 37signals-api mailing list.
Introduction
The Campfire API is implemented as vanilla XML/JSON over HTTP. You can explore the view part of the API (everything that's fetched with GET) through a regular browser. Using Firefox for this is particularly nice as it has a good, simple XML renderer (unlike Safari which just strips the tags and dumps the content).
Authentication
When you're using the API, it's always through an existing user in Campfire. There's no special API user. So when you use the API as "david", you get to see and work with what "david" is allowed to. Authenticating is done with an authentication token, which you'll find on the "Edit my Campfire account" screen in Campfire (click the "Reveal authentication token for API" link).
When using the authentication token, you don't need a separate password. But since Campfire uses HTTP Basic Authentication, and lots of implementations assume that you want to have a password, it's often easier just to pass in a dummy password, like X.
Example using the authentication token and a dummy password through curl:
curl -u 605b32dd:X https://sample.campfirenow.com/room/1.xmlcurl -u 605b32dd:X https://sample.campfirenow.com/room/2.jsonRemember that anyone who has your authentication token can see and change everything you have access to. So you want to guard that as well as you guard your username and password. If you come to fear that it has been compromised, just chang your regular password and the authentication token will change too.
Reading through the API
The Campfire API has two category of actions for reading: Show and list. Show returns a single record and list returns a collection. There's usually just a single show action for each resource, but many lists. All these actions are done through GET, which also means that they're all easily explorable through a browser as described above.
A few examples of reading with curl:
curl -u 605b32dd:X https://sample.campfirenow.com/rooms.xmlcurl -u 605b32dd:X https://sample.campfirenow.com/room/1.xmlIf the read is successful, you'll get an XML response back along with the status code "200 OK".
Writing through the API
Writing through the API is almost as easy as reading, but you can't explore it as easily through the browser. Regardless of your implementation language, though, using curl to play first is a great idea. It makes it very easy to explore the API and is perfect for small scripts too.
When you're writing through the API, you'll be sending XML or JSON to Campfire. You need to let the system know that fact by adding the appropriate content type header : "Content-type: application/xml" or "Content-type: application/json". Then you just include the XML or JSON of the resource in the body of your request.
A few examples creating new resources, first with the XML inline, second referencing the XML from a file:
curl -u 605b32dd:X -H 'Content-Type: application/xml' \
-d '<message><body>Hello</body></message>' https://sample.campfirenow.com/room/1/speak.xmlcurl -u 605b32dd:X -H 'Content-Type: application/xml' \
-d @message.xml https://sample.campfirenow.com/room/1/speak.xmlSimilarly, if you want to use JSON:
curl -u 605b32dd:X -H 'Content-Type: application/json' \
-d '{"message":{"body":"Hello"}}' https://sample.campfirenow.com/room/1/speak.jsonThe response to a succesful write operation is the status code "201 Created". We also include the complete XML or JSON for the final resource in the response. This is because you can usually get away with creating a new resource with less than all its regular attributes.
Dealing with failure
If a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like:
HTTP/1.1 404 The record could not be found
Date: Thu, 16 Mar 2006 17:41:40 GMT
...
Note that, in general, if a request causes a new record to be created (like a new message, or to-do item, etc.), the response will use the "201 Created" status. Any other successful operation (like a successful query, delete, or update) will use a 200 status code.
See the Ruby wrapper example for more inspiration.
SSL Note: A request made against an account that has SSL turned on will get a redirect answer back. Be sure to call over https for an account that requires that.
Conventions in the API documentation
In the documentation that follows, the following notation is used:
#{text}: Indicates text that should be replaced by your own data...: Indicates content from the response has been elided for brevity in documentation. See the list of data responses at the end of the page for a full description of the format of that response type.
All text and design is copyright ©1999-2007 37signals, LLC. All rights reserved.