Getting Started with rlatr

API Basics

For consistency, all examples use cURL.

Setup

A request to the rlatr API uses basic authentication, requiring your API key and a secret key. Both are available on the account page. Your secret key should, well, be kept a secret, but it may be regenerated if it has been leaked.

http://[api key]:[secret key]@rlatr.com/api/[version]/schedule

Response Format

Currently, all responses are JSON formatted. Other formats will be available with the next API release, scouts honor. Whenever you make a request to the API it will respond with status message:

    {
      "success" : {
        "id" : 123456
      }
    }
  

    {
      "fail" : {
        "errors" : ["Need more cowbell"]
      }
    }
  

API Methods

Create

Job urls are scheduled using a POST request.

curl -u api_key:secret_key 
    -d at=2011-07-26T20:34:56-05:00 
    --data-urlencode uri=http://myapp.com/do/something 
      http://rlatr.com/api/v1ish/schedule
  

Update

A job request can be updated via a PUT request as long as it hasn't been completed. The parameters are the same as in creation. You must include the id of the job.

curl -u api_key:secret_key 
    -X PUT
    -d method=post
    http://rlatr.com/api/v1ish/schedule/[id]
  

Delete

A job request can be deleted via a DELETE request as long as it hasn't been completed. You must include the id of the job.

curl -u api_key:secret_key 
    -X DELETE
    http://rlatr.com/api/v1ish/schedule/[id]
  

Handling Errors

When a scheduled request fails, it's a sad day for us all. We will retry the request at scheduled intervals: 10 seconds later, 1 minute later, and 10 minutes later. Each attempt is logged and available to view on our web app.

If your server responds with an error, it will be logged in the debugger with the information reguarding the error, and the body of the response.

Callbacks

Optionally, you may include a callback uri when scheduling.

curl -u api_key:secret_key 
    -d at=2011-07-26T20:34:56-05:00 
    --data-urlencode callback_uri=http://myapp.com/handle/callback
    --data-urlencode uri=http://myapp.com/do/something 
      http://rlatr.com/api/v1ish/schedule
  

After the scheduled request is complete we will POST the results to the callback uri. At this time, if the callback fails it will not be retried. The following parameters will be included, encoded as JSON:

Redirects are not followed in callbacks!

Security

SSL

SSL is not supported while in beta, but it will be available in the future.

Validating Requests

An extra HTTP header is included in all requests, allowing you to validate the request came from rlatr. Here's how to use it:

1. Calculate the expected signature by taking the request url and appending your secret key. http://myapp.com/do/something + [secret_key]
2. Sign the resulting string with HMAC-SHA1, using your account secret key as the hash key.
3. Encode the result in Base 64
4. Grab the value of the X-RLatr-Signature header and compare it to your result, if they match then you're good to go!

The following example uses Ruby, but the functionality is available in most programming languages. If your secret key is 12345:

url_with_key = 'http://myapp.com/do/something' + '12345'
digest       = OpenSSL::Digest::Digest.new('sha1')
signature    = OpenSSL::HMAC.digest(digest, '12345', url_with_key)
Base64.encode64(signature) # => ZriJ80klaSFl7aCc8U2Ndam4E4I=
  

Additional Support

If you have any questions or feel there is something we didn't cover here feel free to email .