I’m still working on the documentation, but figured I’d go ahead and post what I’ve written and start getting feedback. Let me know what you think!

ImThere API – Beta

Introduction

Write something pretty here.

Concepts

Authentication

Authentication is required on all actions which change data (POST, PUT, DELETE), and recommended for everything else. When authenticated, all times will be represented in the authenticating user’s timezone. When not authenticated, all times will be represented in Central time.

For the time being, HTTP Basic Authentication is the only supported authentication scheme. When authenticating via Basic Auth, use your registered username or email address as the username component.

RESTful Resources

The ImThere API tries to conform as much as possible to the design principles of REST. You’ll find that you can simply change the file extension on most any request to get results in the format of your choice. This document notes which formats are available for each method.

ImThere presently supports the following formats: XML, JSON, RSS, ICS.

Parameters

Some API methods take optional or requisite parameters. Where applicable, we’ve documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings.

Standard parameters:

• id: The id of the resource you’re trying to retrieve. Note: On events, venues and artists, only the initial numeric part of the id is required. On users, the id can either be the user’s username (recommended) or their numeric id. Ex: http://imthere.com/events/4.xml or http://imthere.com/events/4-imthere-launch-party.xml
• {type}_id: The id of a parent object in subresources. Ex: http://imthere.com/users/#{user_id}/events.xml, #{user_id} is replaced with the id of the user you want to get events for. http://imthere.com/users/Chad/events.xml
• format: The format you’d like your response in (xml, json, rss, etc.)

HTTP Requests

Unless otherwise noted, methods exposed by the ImThere API require a GET request. Methods that post updates or direct messages require a POST.

When requesting XML, the response is UTF-8 encoded. Symbols and characters outside of the standard ASCII range are translated to HTML entities.

HTTP Status Codes

The ImThere API attempts to return appropriate HTTP status codes for every request.

• 200 OK: everything went awesome.
• 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided aren’t valid.
• 403 Forbidden: we understand your request, but are refusing to fulfill it.
• 404 Not Found: either you’re requesting an invalid URI or the resource in question doesn’t exist (ex: no such event).
• 422 Unprocessable Entity: Whatever you sent us didn’t validate. An accompanying error message should explain why.
• 500 Internal Server Error: we did something wrong. The ImThere team has been notified of the error, but you can nag us if you think we’re taking too long to fix it.
• 502 Bad Gateway: returned if ImThere is down or being upgraded.
• 503 Service Unavailable: the ImThere servers are up, but are overloaded with requests. Try again later.

Custom HTTP headers

Index actions will include a TOTAL-ENTRIES HTTP header, which is a count of the total number of results. This eliminates the need to page through all the data just to get a count.

Events

Notes

• start_time / end_time attributes are always given in the authenticated user’s timezone.
• If the timeless attribute is true, actual start time is at the “beginning of the given day”, actual end time is at the “end of the given day”. This will be refactored soon.
• details attribute supports Textile formatting.
• local attribute determines whether the event is shown only to users in the local area of the event (true), or to all users (false)
• rt attribute is true for “real-time events” – events submitted from a mobile phone. This attribute is read-only – you can’t change it’s value.

index

Returns #{per_page} events, sorted by popularity (hotness).

Notes: When specifying ‘when’ parameter, events are ordered by occurrence, soonest/most recent first. Somewhat screwy… Will have better sort options soon…
Method: GET
Formats: XML, JSON, RSS, ICS
URLs:

• http://imthere.com/events.#{format}
• http://imthere.com/users/#{user_id}/events.#{format}: Events a user has said ImThere to. Note: Only shows past events for non-friends.
• http://imthere.com/venues/#{venue_id}/events.#{format}: Events at a venue.
• http://imthere.com/artists/#{artist_id}/events.#{format}: Events an artist performed at.

Parameters:

• page: Optional. Gets the #{per_page} next most popular events. Ex: http://imthere.com/events.xml?page=2
• per_page: Optional. Sets the number of events you want to get at once. Must be between 1 and 100. Defaults to 8.
• type: Optional. Only return events of a specific type.
• q: Optional. A search string.
• when: Optional. Only return events within a specified range. Specify one of “upcoming”, “past”, “now”

create

Create a new event.

Method: POST
Formats: XML
URL: http://imthere.com/events.#{format}

show

Returns a single event, specified by the id parameter.

Method: GET
Formats: XML, JSON, ICS
URL: http://imthere.com/events/#{id}.#{format}

update

Update an event.

Method: PUT
Formats: XML
URL: http://imthere.com/events/#{id}.#{format}

delete

Delete an event. Currently not enabled.

Method: DELETE
Formats: XML
URL: http://imthere.com/events/#{id}.#{format}

picture

Returns an event’s default picture.

Method: GET
Formats: XML, JSON
URL: http://imthere.com/events/#{event_id}/picture.#{format}

experience

Say ImThere to event.

Method: POST
Formats: XML
URL: http://imthere.com/events/#{event_id}/experience.#{format}

unexperience

Undo ImThere.

Method: DELETE
Formats: XML
URL: http://imthere.com/events/#{event_id}/experience.#{format}

Venues

index

Returns #{per_page} venues, sorted by popularity (hotness).

Method: GET
Formats: XML, JSON, RSS
URLs:

• http://imthere.com/venues.#{format}
• http://imthere.com/users/#{user_id}/venues.#{format}: Venues a user has said BeenThere to.
• http://imthere.com/users/#{user_id}/favorite_venues.#{format}: Venues a user has favorited.

Parameters:

• page: Optional. Gets the #{per_page} next most popular venues. Ex: http://imthere.com/venues.xml?page=2
• per_page: Optional. Sets the number of events you want to get at once. Must be between 1 and 100. Defaults to 8.
• type: Optional. Only return venues of a specific type.
• q: Optional. A search string.

create

Create a new venue.

Method: POST
Formats: XML
URL: http://imthere.com/venues.#{format}

show

Returns a single venue, specified by the id parameter.

Method: GET
Formats: XML, JSON, ICS
URL: http://imthere.com/venues/#{id}.#{format}

update

Update a venue.

Method: PUT
Formats: XML
URL: http://imthere.com/venues/#{id}.#{format}

delete

Delete a venue. Currently not enabled.

Method: DELETE
Formats: XML
URL: http://imthere.com/venues/#{id}.#{format}

picture

Returns a venue’s default picture.

Method: GET
Formats: XML, JSON
URL: http://imthere.com/venues/#{venue_id}/picture.#{format}

experience

Say BeenThere to venue.

Method: POST
Formats: XML
URL: http://imthere.com/venues/#{venue_id}/experience.#{format}

unexperience

Undo BeenThere.

Method: DELETE
Formats: XML
URL: http://imthere.com/venues/#{venue_id}/experience.#{format}

favorite

Add venue to favorites.

Method: POST
Formats: XML
URL: http://imthere.com/venues/#{venue_id}/favorite.#{format}

unfavorite

Remove venue from favorites.

Method: DELETE
Formats: XML
URL: http://imthere.com/venues/#{venue_id}/favorite.#{format}

Artists

index

Returns #{per_page} artists, sorted by popularity (hotness).

Method: GET
Formats: XML, JSON, RSS
URLs:

• http://imthere.com/artists.#{format}
• http://imthere.com/users/#{user_id}/artists.#{format}: artists a user has said SeenThem to.
• http://imthere.com/users/#{user_id}/favorite_artists.#{format}: artists a user has favorited.

Parameters:

• page: Optional. Gets the #{per_page} next most popular artists. Ex: http://imthere.com/artists.xml?page=2
• per_page: Optional. Sets the number of events you want to get at once. Must be between 1 and 100. Defaults to 8.
• type: Optional. Only return artists of a specific type.
• q: Optional. A search string.

create

Create a new artist.

Method: POST
Formats: XML
URL: http://imthere.com/artists.#{format}

show

Returns a single artist, specified by the id parameter.

Method: GET
Formats: XML, JSON, ICS
URL: http://imthere.com/artists/#{id}.#{format}

update

Update an artist.

Method: PUT
Formats: XML
URL: http://imthere.com/artists/#{id}.#{format}

delete

Delete an artist. Currently not enabled.

Method: DELETE
Formats: XML
URL: http://imthere.com/artists/#{id}.#{format}

picture

Returns an artist’s default picture.

Method: GET
Formats: XML, JSON
URL: http://imthere.com/artists/#{artist_id}/picture.#{format}

experience

Say SeenThem to artist.

Method: POST
Formats: XML
URL: http://imthere.com/artists/#{artist_id}/experience.#{format}

unexperience

Undo SeenThem.

Method: DELETE
Formats: XML
URL: http://imthere.com/artists/#{artist_id}/experience.#{format}

favorite

Add artist to favorites.

Method: POST
Formats: XML
URL: http://imthere.com/artists/#{artist_id}/favorite.#{format}

unfavorite

Remove artist from favorites.

Method: DELETE
Formats: XML
URL: http://imthere.com/artists/#{artist_id}/favorite.#{format}

Users

index

Returns #{per_page} users, sorted by popularity (hotness).

Method: GET
Formats: XML, JSON, RSS
URLs:

• http://imthere.com/users.#{format}
• http://imthere.com/events/#{event_id}/users.#{format}: Users that said ImThere to an event.
• http://imthere.com/venues/#{venue_id}/users.#{format}: Users that said BeenThere to a venue.
• http://imthere.com/venues/#{venue_id}/fans.#{format}: Users that have favorited a venue.
• http://imthere.com/artists/#{artist_id}/users.#{format}: Users that said SeenThem to an artist.
• http://imthere.com/artists/#{artist_id}/fans.#{format}: Users that have favorited an artist.

Parameters:

• page: Optional. Gets the #{per_page} next most popular users. Ex: http://imthere.com/users.xml?page=2
• per_page: Optional. Sets the number of events you want to get at once. Must be between 1 and 100. Defaults to 8.
• q: Optional. A search string.

show

Returns a single user, specified by the id parameter.

Method: GET
Formats: XML, JSON, ICS
URL: http://imthere.com/users/#{id}.#{format}

picture

Returns a user’s default picture.

Method: GET
Formats: XML, JSON
URL: http://imthere.com/users/#{user_id}/picture.#{format}

befriend

Add a user to your friends list.

Method: POST
Formats: XML
URL: http://imthere.com/users/#{user_id}/friend.#{format}

unfriend

Remove a user from your friends list.

Method: DELETE
Formats: XML
URL: http://imthere.com/users/#{user_id}/friend.#{format}

Account

status

Set your user status.

Method: POST
Formats: XML
URL: http://imthere.com/account/status.#{format}