Introduction

This document details the ScrnShots.com public API. The API is available to any developer who wishes to create a tool that interfaces with ScrnShots.com through its upload/storage API and its related APIs.

Document & API State

Currently, we are still working on the full API for ScrnShots.com. However, any API methods that are documented within this document will be considered to be stable and will be supported in the future by ScrnShots.

Restful Resources

The ScrnShots API conforms to REST (Representational State Transfer) as much as possible. It uses the HTTP verbs through unique resource URIs to act on them.

Authentication

Currently, ScrnShots implements HTTP Basic Authentication for actions that require authentication (marked in API docs). To perform actions that require authentication use the ScrnShots username and password via HTTP Basic Auth.

A more secure method of authentication is planned, but not ready to be released at the time of this writing.

 

On all requests that require authentication, if the user is does authenticate you will get a 401 Response with the following string: Could't authenticate you 

Screenshot RSS Feeds

Although they are not entirely documented here yet, most pages (currently excluding search pages) that list screenshots include an RSS feed. To access the feed, simply add ".rss" to the end of the URL. 

Screenshot Methods

Upload a Screenshot (Authentication Required)

Uploads a screenshot to the system with the passed in parameters

URL: http://www.scrnshots.com/screenshots.xml

HTTP Method: POST

Format: XML

Paramaters: 

• screenshot[uploaded_data] => This parameter should hold the screenshot file to be uploaded
• screenshot[description] => This is the description field where users can describe the screenshot. Max Length = TODO
  
• screenshot[tag_list] => This is a space seperated list of tags to be applied to the screenshot. Eg "design blue_design big_long_tag"
  
• screenshot[source_url] => Setting this parameter will create a link on the screenshot page to the url provided. This can be used to give credit to the screenshot creators
  

Example cURL Post:

Here is an example of posting a screenshot using the command line tool cURL (This is should all be one line but is broken with '\' to make it easier to read):

curl http://www.scrnshots.com/screenshot.xml -H 'Accept: application/xml' \

     -F 'screenshot[uploaded_data]=@/path-to-image;type=image/png' \

     -F 'screenshot[description]=This is a really great screenshot' \

     -F 'screenshot[tag_list]=blue design form_design' \

     -F 'screenshot[source_url]=www.scrnshots.com' \

     -u my-scrnshots-username:my-scrnshots-password --basic

 

Example Success Response:

If the screenshot upload was successful it will return the screenshot as xml:

 

<screenshot>
  <created-at type="datetime">Thu May 15 14:51:08 +0000 2008</created-at>
  <description>
    This is a really great screenshot
  </description>
  <user href="http://www.scrnshots.com/users/my-scrnshots-username">my-scrnshots-username</user>
  <link>
    http://www.scrnshots.com/users/my-scrnshots-username/screenshots/5343
  </link>
  <content-type>image/png</content-type>
  <images>
    <full-size src="http://s3.amazonaws.com/scrnshots.com/screenshots/5343/sc_email.png"/>
    <large src="http://s3.amazonaws.com/scrnshots.com/screenshots/5343/sc_email_large.png"/>
    <medium src="http://s3.amazonaws.com/scrnshots.com/screenshots/5343/sc_email_med_rect.png"/>
    <small src="http://s3.amazonaws.com/scrnshots.com/screenshots/5343/sc_email_small_square.png"/>
  </images>
  <comments-count>0</comments-count>
  <tags>
    <tag href="http://www.scrnshots.com/users/my-scrnshots-username/tags/blue">blue</tag> 

    <tag href="http://www.scrnshots.com/users/my-scrnshots-username/tags/design">design</tag> 

    <tag href="http://www.scrnshots.com/users/my-scrnshots-username/tags/form_design">form_design</tag>  

  </tags>
</screenshot>

Example Error Response:

Otherwise, it will return error messages as XML:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Uploaded data Please select a file</error>
  <error>Uploaded data Please select a valid file type</error>
  <error>Filename can't be blank</error>
</errors>

The upload file must be smaller than 5mb and be of the type PNG, JPG or GIF. Errors will be returned if these are not met.

User Methods

Get User Details

Returns the user's detailed information

URL: http://www.scrnshots.com/users/{user_login}.{format}

HTTP Method: GET

Format: XML, JSON

Paramaters: None

Example XML Response:

<user>

  <id>1</id>

  <login>login_name</login>

  <about-me>I am so great</about-me>

  <website>www.scrnshots.com</website>

  <avatars>

    <large>http://full-url.png</large>

    <medium>http://full-url.png</medium>

    <tiny>http://full-url.png</tiny>

  </avatars>

</user>

 

Example JSON Response:

{"user": {"id": 1, "login": "login_name", "about_me": "I am so great", "website": "www.scrnshots.com" }}

User Contacts Methods

Get User's Contacts

Returns the details of all the user's contacts.

URL: http://www.scrnshots.com/users/{user_login}/contacts.{format}

HTTP Method: GET

Format: XML, JSON

Paramaters: None

Example XML Response:

<contacts type="array">
  <user>
    <about-me>I am great</about-me>
    <id>2</id>
    <login>scnrshots-user-name</login>
    <website>http://www.my-website.com</website>
  </user>
</contacts>

 

Example JSON Response:

[{"user": {"about_me": I am great, "website": http://www.my-website.com, "id": 2, "login": "scrnshots-user-name"}}]

Get a User's Tags

Returns all of the user's tags and the number of times they've used it.

URL: http://www.scrnshots.com/users/{user_login}/tags.{format}

HTTP Method: GET

Format: XML

Paramaters: None

Example Response:

<tags>
  <tag>
    <count>1</count>
    <name>design</name>
  </tag>
  <tag>
    <count>2</count>
    <name>mac</name>
  </tag>
  <tag>
    <count>3</count>
    <name>ScrnShots</name>
  </tag>
</tags>