Moment REST web service interface

The Moment REST API allows you to create, edit, and delete delayed http requests.

Getting started with the Moment API

Since the Moment API is based on REST principles, it's very easy to write and test applications. You can access Moment API endpoints via standard HTTP requests (GET, POST, PUT, and DELETE) using any HTTP client. Nearly every web programming language has a capable HTTP client.

Authentication

The Moment API requires that you supply an API key with each request. Your API key is like a password and should be kept secret. Sign up to receive an API key. If your API key becomes compromised, a replacement API key can be generated via the Settings menu.

Include your API key as an HTTP parameter on every request, as shown here:

https://momentapp.com/resource/path.json?apikey=[your_api_key]

It is recommended that you use HTTPS whenever interacting with the Moment API key for increased security.

Response Format

The Moment API currently supports the JSON response format. Other formats (e.g. XML, RSS, YAML) are being considered for addition based on demand. To ensure that you receive a consistent response format, make sure to include a ".json" extension on each request.

Request Encoding

All requests made to the Moment API should be escaped. Nearly every web programming language has built-in functionality to escape special characters. Consider the following Ruby example:

URI.escape('https://momentapp.com/example.json?text=This is text&code=tH1sI5c0d3')
=> "https://momentapp.com/example.json?text=This%20is%20text&code=tH1sI5c0d3"

URI.unescape('https://momentapp.com/example.json?text=This%20is%20text&code=tH1sI5c0d3')
=> "https://momentapp.com/example.json?text=This is text&code=tH1sI5c0d3"

Note: We have not escaped the URIs in this documentation for the sake of clarity.

Error handling

While we make every attempt to ensure that each job is successful, an HTTP request can fail due to a number of factors that are out of our control. The most common cause of failure is an unresponsive URI. Make sure to encode URIs before sending them to Moment and test each URI with Curl or another HTTP client to ensure that it returns a 2xx HTTP response code.

If a request fails (i.e. Moment does not receive a 2xx HTTP response code), the request is retried at each of 10 seconds, 2 minutes, 15 minutes, 2 hours, and 24 hours after the original request until it succeeds or has exhausted every interval.

API errors

Moment responds to every API request that is received with a 'success' or 'error' response. Errors are returned when Moment cannot process a request. The most common cause of errors are invalid parameters. Your app can handle API errors by reacting to the response.

Example error response:

{
  "error":{
    "[parameter]":"[message]"
  }
}

Scheduling a new job (delayed http request)

A "job" is a scheduled HTTP request. The following API resource is used to programmatically create Moment jobs.

Example request:

POST https://momentapp.com/jobs.json?
  job[at]=2011-01-31T18:36:21&
  job[method]=POST&
  job[uri]=http://yourapp.com/?var1=true&var2=false&
  apikey=[your_api_key]

Example cURL request:

curl -H "Content-Type: application/json" -d "{ 'job':{ 'uri':'http://yoursite.com', 
  'at':'2011-01-31T18:36:21', 'method':'POST' }, 'apikey':'[your_api_key]' }" 
  https://momentapp.com/jobs.json

Example response:

{
  "success":{
    "job":{
      "id":"[unique_job_id]",
      "uri":"http://yourapp.com:80/?var1=true&var2=false",
      "method":"POST",
      "at":"2011-01-31 18:36:21 -0800"
    }
  }
}

Updating a scheduled job (delayed http request)

The following API resource is used to programmatically update scheduled Moment jobs. A "job" is a scheduled HTTP request.

Example request:

PUT https://momentapp.com/jobs/[job_id].json?
  job[at]=2011-01-31T18:36:21&
  job[method]=POST&
  job[uri]=http://yourapp.com/?var1=true&var2=false&
  apikey=[your_api_key]

Example response:

{
  "success":{
    "job":{
      "id":"[unique_job_id]",
      "uri":"http://yourapp.com:80/?var1=true&var2=false",
      "method":"POST",
      "at":"2011-01-31 18:36:21 -0800"
    }
  }
}

Delete a scheduled job (delayed http request)

The following API resource is used to programmatically delete scheduled Moment jobs. A "job" is a scheduled HTTP request.

Example request:

DELETE https://momentapp.com/jobs/[job_id].json?
  apikey=[your_api_key]

Example response:

{
  "success":{
    "message":"Job deleted"
  }
}

Callbacks

A callback is a POST request that Moment makes to a callback URI following the successful completion of a job (i.e. a 2xx response is received). You can assign a callback URI when you schedule a job. Callback URIs typically represent a public listener hosted by the scheduler that receives callback data for further processing.

The body of the callback includes JSON data in the following format:

{
  "response_http_version":[response http version],
  "response_code":[response code],
  "response_code_type":[response code type],
  "response_content_length":[response content length],
  "response_content_type":[response content type],
  "response_body":[response body]
}

What else can we tell you?

While we hope this documentation is useful, we're pretty sure we could make it better with your help. If you think we skipped something important or didn't do a good job explaining something, please let us know!