The Highrise API is implemented as vanilla XML over HTTP using all four verbs (GET/POST/PUT/DELETE). Every resource, like Post, Comment, or Task, has their own URL and are manipulated in isolation. In other words, we've tried to make the API follow the REST principles as much as we can.
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). Pretty much any URL in Highrise can be viewed in its XML form by adding the .xml extension. So /people/4 becomes /people/4.xml if you want to see the XML version.
When you're using the API, it's always through an existing user in Highrise. 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 "My Info" screen in Highrise (click the "Reveal authentication token for feeds/API" link).
When using the authentication token, you don't need a separate password. But since Highrise 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://example.highrisehq.com/people/1.xmlRemember 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, you can regenerate it at any time from the "My Info" screen in Highrise.
Note that the /me.xml endpoint is the one exception to token authentication: you can use a username and password to authenticate against this action. This allows developers to obtain the token for a user, given that user's username and password, which makes it easier for users to authenticate on mobile platforms and the like.
The Highrise 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://example.highrisehq.com/kases/5.xmlcurl -u 605b32dd:X https://example.highrisehq.com/people/27/notes.xmlIf the read is successful, you'll get an XML response back along with the status code "200 OK".
Creating, updating, and deleting resources 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 creating and updating resources, you'll be sending XML into Highrise. You need to let the system know that fact by adding the header "Content-type: application/xml", so we know that it's not regular form-encoded data coming in. Then you just include the XML 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 '<kase><name>Important matters</name></kase>' https://example.highrisehq.com/kases.xmlcurl -u 605b32dd:X -H 'Content-Type: application/xml' \
-d @note.xml https://example.highrisehq.com/people/5/notes.xmlThe response to a succesful creation is the status code "201 Created". You can get the URL of the new resource in the Location header (such that you know where to update your new resource in the future). We also include the complete XML 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. Especially attributes like created_at can be helpful to get back from the creation.
Updating resources is done through the PUT verb and against the URL of the resource you want to update. A few examples:
curl -u 605b32dd:X -X PUT -H 'Content-Type: application/xml' \
-d '<kase><name>Really important matters</name></kase>' https://example.highrisehq.com/kases/5.xmlcurl -u 605b32dd:X -X PUT -H 'Content-Type: application/xml' \
-d @note.xml https://example.highrisehq.com/notes/27.xmlThe response to a successful update is "200 OK".
Finally, you can delete resources (if you're allowed to) using the DELETE verb. A few examples of that:
curl -u 605b32dd:X -X DELETE https://example.highrisehq.com/kases/5.xmlcurl -u 605b32dd:X -X DELETE https://example.highrisehq.com/notes/27.xmlNote that you don't need to pass the content-type header because you're not sending any XML. The response to a successful delete is "200 OK".
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.
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.
XML is not the only other language than HTML you can make Highrise speak. We're also fairly fluent in Atom, CSV, and vCards. To subscribe to recordings (notes, emails, and comments), it's often easier to use the Atom feeds than to go through the XML API. Try browsing around Highrise to find the recording feeds. They're linked up with link-tags in the head of the HTML. For example, there's /recordings.atom for the getting the 25 most recent recordings across all subjects (people, companies, and cases). And there's /people/1/recordings.atom for getting just the last 25 about the person with ID = 1.
All parties (people and companies) can be retrieved in vCard form too. Just append the .vcf extension to the URL, like /people/4.vcf.
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.In addition to the raw API, we've also built Ruby wrapper for the API. To use this wrapper, you'll install Active Resource. Do this with:
gem install activeresourceNow you can try starting an IRB session to play around with the API like this:
SITE=https://1d93c8294:X@sample.highrisehq.com/ irb -r highrise.rb
irb(main):001:0> david = Highrise::Person.find(1)
irb(main):002:0> david.name
=> "David Heinemeier Hansson"The SITE environment should be set to your account URL with the authentication token prefixed followed by a colon and the dummy X. Remember to pick either http or https according to what your account is to up for.