The ScreenSteps Live API Developer Guide
The ScreenSteps Live API uses REST to retrieve manuals from your ScreenSteps Live account via xml.
Urls
The request urls are pretty simple. Currently the following requests are supported:
/api/manuals |
Retrieve a list of all public manuals for an account |
/api/manuals/:manual_id |
Retrieves the table of contents for a single manual. The manual id can be the id number for a manual or the permalink that you set up on ScreenSteps Live. |
/api/manuals/:manual_id/lessons/:lesson_id |
Retrieves the content of a lesson in a manual. Also retrieves basic information about the manual (title, and id) as well as the title and id of the next and previous lessons in a manual. |
By default only public manuals will be retrieved. If you wish to retrieve a manual that is protected then you can add the “?show_protected=true” parameter to the end of the url.
Required Headers
The following headers are required when making a request:
Date |
The current time and date in http format (e.g. Fri, 11 Jul 2008 18:24:47 GMT). |
Content-Type |
Should be set to “application/xml” |
Authorization |
This is the authorization string that you will need to compute for each request (explained below) |
Authorization String
The Authorization String is formed by creating an HMAC Sha1 digest of the ‘StringToSign’ using your ScreenSteps Live API key as a salt. The result of this operation is then Base64 encoded.
The StringToSign is formed as follows:
ScreenStepsLiveAccountUrl + ":" + RequestPath + ":" + DateHeader
So, if my account were “example” and I was requesting a manual of id 5 my StringToSign would look like this:
example.screenstepslive.com:/api/manuals/5:Fri, 11 Jul 2008 18:24:47 GMT
If I wanted to request protected manuals then the string would be:
example:/api/manuals/5?show_protected=true:Fri, 11 Jul 2008 18:24:47 GMT
Here are some code examples for forming the Authorization String:
Ruby
def encode(string_to_sign)
digest = OpenSSL::Digest::Digest.new('sha1')
b64_hmac =
Base64.encode64(
OpenSSL::HMAC.digest(digest, ENV['SCREENSTEPS_LIVE_API_KEY'], string_to_sign)).strip
b64_hmac
end
PHP
private function encode($data) {
$hasher =& new Crypt_HMAC($this->api_key, "sha1");
$digest = $hasher->hash($data);
return base64_encode(pack('H*', $digest));
}
What You Get Back
ScreenSteps Live will return XML. Here are some examples of XML content:
Manauls
<?xml version="1.0" encoding="UTF-8"?>
<manuals>
<manual>
<id>16</id>
<title>MediaNotes</title>
<message>This is the message for my manual.</message>
<private>false</private>
<position>2</position>
<url>http://bmls.screenstepslive.com/manuals/16</url>
</manual>
<manual>
<id>40</id>
<title>ScreenSteps's</title>
<message></message>
<private>false</private>
<position>3</position>
<url>http://bmls.screenstepslive.com/manuals/40</url>
</manual>
<manual>
<id>15</id>
<title>How to use ScreenSteps Live 2</title>
<message>This is a test.</message>
<private>false</private>
<position>4</position>
<url>http://bmls.screenstepslive.com/manuals/ScreenSteps2</url>
</manual>
</manuals>
Individual Manual
<?xml version="1.0" encoding="UTF-8"?>
<manual>
<title>MediaNotes</title>
<id>16</id>
<url>http://bmls.screenstepslive.com/manuals/16</url>
<permalink></permalink>
<private>false</private>
<message>This is the message for my manual.</message>
<sections>
<section>
<title>Getting Started</title>
<position>0</position>
<lessons>
<lesson>
<id>37</id>
<title>Opening the Example Project File</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=37</url>
</lesson>
<lesson>
<id>49</id>
<title>Creating a MediaNotes Project</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=49</url>
</lesson>
<lesson>
<id>50</id>
<title>Playback Controls</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=50</url>
</lesson>
<lesson>
<id>277</id>
<title>Cherry Picking a Change from One Local Branch to Another</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=277</url>
</lesson>
</lessons>
</section>
<section>
<title>Timeline List</title>
<position>2</position>
<lessons>
<lesson>
<id>125</id>
<title>Timeline List Overview</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=125</url>
</lesson>
</lessons>
</section>
<section>
<title>Working With Tags</title>
<position>3</position>
<lessons>
<lesson>
<id>40</id>
<title>Entering a New Tag</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=40</url>
</lesson>
<lesson>
<id>38</id>
<title>Tagging an Event Method 1: Create Event and Then Tag</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=38</url>
</lesson>
<lesson>
<id>39</id>
<title>Tagging an Event Method 2: Tag Location in Video</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=39</url>
</lesson>
<lesson>
<id>77</id>
<title>Importing a Tag Set File into MediaNotes</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=77</url>
</lesson>
</lessons>
</section>
<section>
<title>Tag Manager</title>
<position>4</position>
<lessons>
<lesson>
<id>60</id>
<title>Creating or Opening a Tag Manager File</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=60</url>
</lesson>
<lesson>
<id>61</id>
<title>Creating a Tag in a Tag Set</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=61</url>
</lesson>
<lesson>
<id>76</id>
<title>Exporting a Tag Set File From the Tag Manager</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=76</url>
</lesson>
</lessons>
</section>
</sections>
<tags>
<tag>
<name>Git</name>
<count>1</count>
</tag>
<tag>
<name>Project</name>
<count>1</count>
</tag>
<tag>
<name>ScreenSteps 2</name>
<count>2</count>
</tag>
</tags>
</manual>
Lesson In a Manual
<?xml version="1.0" encoding="UTF-8"?>
<lesson>
<manual>
<id>16</id>
<title>MediaNotes</title>
<url>http://bmls.screenstepslive.com/manuals/16</url>
<next_lesson>
<title>Cherry Picking a Change from One Local Branch to Another</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=277</url>
<id>277</id>
</next_lesson>
<previous_lesson>
<title>Creating a MediaNotes Project</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=49</url>
<id>49</id>
</previous_lesson>
</manual>
<id>50</id>
<title>Playback Controls</title>
<url>http://bmls.screenstepslive.com/manuals/show_lesson/16?lesson_id=50</url>
<description></description>
<steps>
<step>
<title>Introduction</title>
<instructions><p>This lesson will review the playback and event editing controls in MediaNotes.</instructions>
</step>
<step>
<title>Playback Controls</title>
<instructions><p>The controls on the left are standard playback controls:</p></instructions>
</step>
<step>
<title>Jump to Events</title>
<instructions><p>The Jump to Next/Previous Event buttons on the right allow you to quickly skip to events in the video/audio file.</p></instructions>
</step>
<step>
<title>Timeline Lock</title>
<instructions><p>The left-most button controls the playback mode. The default mod is &quot;Sync&quot;. In this mode events will automatically be loaded as the video plays. In this example the playhead is over the first event and the event is active.</p></instructions>
</step>
<step>
<title></title>
<instructions><p>Here the playhead has moved onto the second event and that event has become active.</p></instructions>
</step>
<step>
<title>Playback Mode: No Sync</title>
<instructions><p>Click on the playback mode once to switch the mode to &quot;No Sync&quot; (the icon will become a broken chain link). Basically the video or audio file will play straight through. Events will not automatically be loaded.</p></instructions>
</step>
<step>
<title>Loop</title>
<instructions><p>Clicking again on the playback mode button will switch the mode to loop. In this mode the current event will continuously loop during playback.</p></instructions>
</step>
</steps>
</lesson>
That should be enough for you to get started. If you want to play around with an example ScreenSteps Live account that already has lessons in it you can use the following domain and api key:
Domain: example.screenstepslive.com
API Key: 12e5317e88
You can check out some screencasts about the API and get some links to example code at http://www.screensteps.com/screenstep_live/api.php
Tags: API, ScreenSteps Live