API
From Mugshot Developer Wiki
Right now the web services API for mugshot.org exports information that the site would show you anonymously (without any kind of login or authentication).
We want to offer more APIs once we figure out how authentication should work. If you have ideas on that, we're glad to hear them.
In the source code, you can find these APIs in a Java interface called HttpMethods ... it uses Java annotations to map the Java methods to "REST" calls. Methods on the HttpMethods interface that have a UserViewpoint as an argument require a logged-in user or they won't work. Methods that have no UserViewpoint require no authentication.
As of now, only one method in there is interesting to third party apps. Almost everything requires authentication.
Current API
One method, woo!
You can get information on the current song someone is listening to:
http://mugshot.org/xml/nowplaying?who=USER_ID&theme=THEME_ID
This returns some pretty self-explanatory XML describing the current song a user is listening to. It also provides the images and text positions/colors that make up a theme for our "display your current song" flash application. The "theme" parameter is optional, used to hardcode a specific theme instead of just getting the user's current theme.
You could use the /xml/nowplaying call to display a user's current song in any format you like. You could even use the theme information, using html rather than flash - we used flash on the first cut primarily because myspace and other sites don't allow iframes. But if you run your own site, an iframe would work fine. In fact we'd love a patch for an "official" iframe embed.
You can get the USER_ID from someone's /person page (click on the person's name or photo on the site), it has a who= parameter in the URL showing the person's ID.
Similar for the THEME_ID, click on a theme name to get to the theme page which has the theme ID as a parameter.
API Ideas
Let us know what you would find useful.
A method that would be simple to add is a machine-readable version of the /person page, to get someone's profile information such as their name, photo, and whatever else is public. This would be something like:
/xml/getperson?who=USER_ID
and return some simple XML with various public information from someone's profile page.
It would also be simple to export other anonymously-viewable information, such as the current hot links or hot songs.
Authentication is a harder problem, that we'd like help with.
The Rules
We don't have any formal terms of service yet on the APIs. Rest assured, there are no guarantees our service will stay up or be reliable ;-) Also, if you start causing load, bandwidth, or reliability problems we will probably turn your IP address off, at least temporarily until we can talk to you and figure out a solution.
We don't make any "stability guarantees" yet; the APIs may change. If your calls stop working, check back here for an update, if there isn't one then find us online and ask. That said, we'll try not to break things just for the heck of it.
