XML API

If you’re not a programmer or technical type, this post is probably not very exciting. Sorry!

Otherwise, dig this: I just hacked out an read-only XML API for Stormweight. It’s a fairly bare-bones interface, but more will follow. I’ll be using curl in this example, but it should be pretty simple to wrap this with any language that does HTTP GET.

Important: This is an alpha API. Although this document will always reflect the accurate state of the API, I’ll likely be changing the structure as the API matures. The silver lining of this is that the API is still flexible. Please make suggestions at this API-specific Stormweight list

Document History

• 8/17/09 Created document, initial API revision (0.0)
• 8/17/09 Revision 0.1
  • Added /lists/#{list-id}/rankings.xml
  • Added /lists/#{list-id}/group_rankings.xml
  • Added /lists/#{list-id}/ideas/#{idea-id}.xml
  • Fixed authentication issues
  • Added open_membership to /lists/#{list-id}.xml
  • Changed /lists/#{list-id}/ideas.xml to provide two URLs: html_url and xml_url

Authentication

For now, authentication is just HTTP basic auth. I’d like to transition to OAuth fairly soon if there’s substantial API traffic. A request looks something like:

curl http://username:password@www.stormweight.com/whatever_request.xml

List Dashboard

A request to /lists.xml will yield an xml document of the lists available to the authenticated user. Example:

$ curl http://username:password@www.stormweight.com/lists.xml
<?xml version="1.0" encoding="UTF-8"?>
<lists>
  <list>
    <title>List 1</title>
    <url>http://www.stormweight.com/lists/list-1</url>
  </list>
  <list>
    <title>Stormweight Review</title>
    <url>http://www.stormweight.com/lists/list-2</url>
  </list>
</lists>

Individual List Info

To get information about a list, make a GET request to the <url> in /lists.xml, followed by .xml. For example, if we wanted to find out about List 1:

$ curl http://username:password@www.stormweight.com/lists/list-1.xml
<?xml version="1.0" encoding="UTF-8"?>
<list>
  <title>List 1</title>
  <description></description>
  <created_at>2008-11-02 16:53:20 -0800</created_at>
  <updated_at>2009-07-16 22:04:03 -0700</updated_at>
  <open_membership>true</open_membership>
  <anonymous_ideas>true</anonymous_ideas>
  <anonymous_comments>true</anonymous_comments>
  <idea_anonymity_override>false</idea_anonymity_override>
  <ranking_expiration>
    <count>1</count>
    <period>week</period>
  </ranking_expiration>
</list>

List Ideas

A list of ideas is available at lists/#{list-name}/ideas.xml:

$ curl https://username:password@www.stormweight.com/lists/list-1/ideas.xml
<?xml version="1.0" encoding="UTF-8"?>
<ideas>
  <idea>
    <title>Idea 1</title>
    <description>This is an idea</description>
    <created_at>Mon, 17 Aug 2009 12:06:34 -0700</created_at>
    <author>anonymous</author>
    <html_url>https://www.stormweight.com/lists/list-1#idea_1234</url>
    <xml_url>https://www.stormweight.com/lists/list-1/ideas/1234.xml</url>
    <categories>
      <category>Blimp</category>
    </categories>
    <comments>
    </comments>
  </idea>
  <idea>
    <title>Idea 2</title>
    <description></description>
    <created_at>Wed, 15 Jul 2009 15:35:24 -0700</created_at>
    <author>anonymous</author>
    <html_url>https://www.stormweight.com/lists/list-1#idea_314159</url>
    <xml_url>https://www.stormweight.com/lists/list-1/ideas/314159.xml</url>
    <categories>
    </categories>
    <comments>
      <comment>
        <text>Need more specifics</text>
        <author>anonymous</author>
      </comment>
    </comments>
  </idea>
</ideas>

Group Rankings

Make a request to /lists/#{your list name}/group_rankings.xml to find out what the group thinks.

$ curl https://user:pass@www.stormweight.com/lists/list-1/group_rankings.xml
<?xml version="1.0" encoding="UTF-8"?>
<group_rankings>
  <ranking>
    <position>0</position>
    <idea>
      <title>idea 1</title>
      <url>http://www.stormweight.com/lists/list-1/ideas/1337.xml</url>
    </idea>
    <strength>1 @ 29.4%</strength>
  </ranking>
  <ranking>
    <position>1</position>
    <idea>
      <title>idea 2</title>
      <url>http://www.stormweight.com/lists/list-1/ideas/314159.xml</url>
    </idea>
    <strength>1 @ 26.5%</strength>
  </ranking>
</group_rankings>

The Authenticated User’s Rankings

Make a request to /lists/#{your list name}/rankings.xml for the authenticated user’s rankings.

$ curl https://user:pass@www.stormweight.com/lists/list-1/rankings.xml
<?xml version="1.0" encoding="UTF-8"?>
<rankings>
  <ranking>
    <position>0</position>
    <idea>
      <title>idea 1</title>
      <url>http://www.stormweight.com/lists/list-1/ideas/1337.xml</url>
    </idea>
  </ranking>
  <ranking>
    <position>1</position>
    <idea>
      <title>idea 2</title>
      <url>http://www.stormweight.com/lists/list-1/ideas/314159.xml</url>
    </idea>
  </ranking>
</group_rankings>