Get started

To get started:
  1. Request an application key (PhotoDeck account needed)
  2. Upon registration of your application, you should have two keys: the first one is the public API key, the second one is a private secret key shared between PhotoDeck and you (and only you).
    Example:
    API key: 200a3e048fcbf4c9d6392b99a3bd114af4b3700d
    API secret: c37912f3900eb26b14aab91d98832b211cdc7791
    
  3. To call a PhotoDeck API service, you need to set two HTTP headers:
    • X-PhotoDeck-Authorization: API key:signature
    • X-PhotoDeck-Timestamp: current date and time in RFC2822 format
    The signature is the SHA1 hex digest of the following text:
    HTTP method (GET, POST, PUT or DELETE)
    requested URL
    query string (or empty)
    API secret
    copy of the X-PhotoDeck-Timestamp content
    

    Important: the time-stamp should be within a 30 minutes window of the current PhotoDeck servers time.
    If generating a RFC2822 date is too complex, you can revert to a Posix Time / ISO 8601 format (UTC).
    Example of signature calculation for a request to https://api.photodeck.com/ping.xml (assuming that you are running a UNIX system with the sha1sum tool installed):
    $ api_key="200a3e048fcbf4c9d6392b99a3bd114af4b3700d"; api_secret="c37912f3900eb26b14aab91d98832b211cdc7791"
    $ request='/ping.xml'; querystring=''
    $ timestamp=$(date -R)
    $ printf "GET\n$request\n$querystring\n$api_secret\n$timestamp\n" | sha1sum | cut -f1 -d' '
    f2c14a1936a1732fda757b0870e08b1df792c2a5
    $
    
    In this example, the calculated signature is f2c14a1936a1732fda757b0870e08b1df792c2a5 when executed at Fri, 25 Jun 2010 12:39:15 +0200.
    It is now possible to call the service with the following headers:
    X-PhotoDeck-Authorization: 200a3e048fcbf4c9d6392b99a3bd114af4b3700d:f2c14a1936a1732fda757b0870e08b1df792c2a5
    X-PhotoDeck-Timestamp: Fri, 25 Jun 2010 12:39:15 +0200
    
    The signature should be calculated for every request.
    Note: if you can't use SHA1 to calculate the signature, you can revert to MD5. We will auto detect which one is being used.
  4. Call a dummy 'ping' service to make sure that your key and signature are recognized.
    GET https://api.photodeck.com/ping.xml -- include the X-PhotoDeck-Auhorization and X-PhotoDeck-Timestamp HTTP headers
    You should get in return an XML "OK" message.
    Example from a command line, using curl tool:
    $ api_key='200a3e048fcbf4c9d6392b99a3bd114af4b3700d'; api_secret='c37912f3900eb26b14aab91d98832b211cdc7791'
    $ request='/ping.xml'; querystring=''
    $ timestamp=$(date -R)
    $ sign=$(printf "GET\n$request\n$querystring\n$api_secret\n$timestamp\n" | sha1sum | cut -f1 -d' ')
    $ curl -H "X-PhotoDeck-Authorization: $api_key:$sign" -H "X-PhotoDeck-Timestamp: $timestamp" "https://api.photodeck.com$request${querystring:+?$querystring}"
    <?xml version="1.0" encoding="UTF-8"?>
    <reply>
      <request>GET /ping.xml</request>
      <message>OK</message>
    </reply>
    
  5. Now let's call a dummy 'ping_auth' service that requires user authentication. For now, let's use HTTP Basic authentication.
    GET https://api.photodeck.com/ping_auth.xml
    You should get in return an XML "OK" message.
    Example from a command line:
    $ api_key='200a3e048fcbf4c9d6392b99a3bd114af4b3700d'; api_secret='c37912f3900eb26b14aab91d98832b211cdc7791'
    $ request='/ping_auth.xml'; querystring=''
    $ timestamp=$(date -R)
    $ sign=$(printf "GET\n$request\n$querystring\n$api_secret\n$timestamp\n" | sha1sum | cut -f1 -d' ')
    $ curl -H "X-PhotoDeck-Authorization: $api_key:$sign" -H "X-PhotoDeck-Timestamp: $timestamp" -u john@doe.com "https://api.photodeck.com$request${querystring:+?$querystring}"
    Enter host password for user 'john@doe.com':
    <?xml version="1.0" encoding="UTF-8"?>
    <reply>
      <request>GET /ping_auth.xml</request>
      <message>OK</message>
    </reply>
    
    It's also possible to pass a text=some text parameter to the ping and ping_auth methods (in the query string). You should get the same text back in return, enclosed in a <input-text> tag.
    When submitting an authenticated request (using HTTP Basic) to the PhotoDeck API, a session cookie is sent back. Attach that session cookie in subsequent requests. Do not use HTTP Basic at each request.
  6. Now, head over to the API documentation