The ContinuityApp API

The ContinuityApp API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.

API can be accessed via HTTP basic authentication, and OAuth2. We strongly encourage you to use OAuth2 based authentication for your production applications, and use HTTP basic authentication for testing purposes.

We are not restricting API access with rate limits.

If you have any problems or requests please contact support@continuityapp.com.

Schema

All API access is over HTTPS, and accessed from the v1.continuityapp.ws hostname.

$ curl -i https://v1.continuityapp.ws/ping

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept
Server: ContinuityApp Web Services
Content-Length: 19
Date: Fri, 08 Feb 2013 17:47:24 GMT
Cache-control: private
Connection: close

{"response":"pong"}

Authentication

OAuth2

OAuth2 is the preferred way to interact with the ContinuityApp API.

Before starting using OAuth2 you will need to register your App, and obtain a Client ID and Secret Key: this can be easily done at the Create an application page. You will use this data to obtain an access token, and you will use this access token to sign all your requests to the ContinuityApp API. Access token has no expiration date.

You will be required to provide a redirect URL: you can specify a valid URL like http://hostname/oauth_redirect or urn:ietf:wg:oauth:2.0:oob for command line applications. Providing urn:ietf:wg:oauth:2.0:oob as redirect URL users will be provided with an authorization code to be copy/pasted into your application.

require 'oauth2'
require 'launchy'

oauth = OAuth2::Client.new(
  "<client_id>",
  "<secret_key>",
  :authorize_url => "/oauth2/authorize",
  :token_url => "/oauth2/access_token",
  :site => "https://v1.continuityapp.ws/"
)


# Authorization "Code Flow"
Launchy.open(oauth.auth_code.authorize_url(redirect_uri: "urn:ietf:wg:oauth:2.0:oob", scope: 'build_requests_create,user'))
print "A browser window will open, please login with your account and grant access to this App to generate the authorization code. Once done, enter che generated code: "
code = gets.chomp
access_token = oauth.auth_code.get_token(code, redirect_uri: "urn:ietf:wg:oauth:2.0:oob")

# Authorization "Implicit Flow"
# redirect to(oauth.auth_code.authorize_url(redirect_uri: "http://hostname/oauth_redirect"))
# access_token = OAuth2::AccessToken.from_kvform(oauth, params)

require 'net/https'
http = Net::HTTP.new('https://v1.continuityapp.ws', 443)
http.use_ssl = true
http.start do |http|
    request = Net::HTTP::Get.new("/whoami?oauth_token=#{access_token}")
    request.basic_auth 'marco@continuityapp.com', '<api_key>'
    response = http.request(request)
    response.value
    puts response.body
end

$ curl -i https://v1.continuityapp.ws/whoami?oauth_token=<access_token>

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept
Server: ContinuityApp Web Services
Content-Length: 48
Date: Fri, 08 Feb 2013 18:11:03 GMT
Cache-control: private
Connection: close

{"response":{"email":"marco@continuityapp.com"}}

OAuth for Open Source

We support a variant of OAuth Flows to allow Open Source developers to distribute software without worring about Secret Tokens. If you want to write an Open Source software based on ContinuityApp APIs, or you just want to learn more, drop us a line to support@continuityapp.com.

HTTP Basic

HTTP basic authentication is the insecure way to interact with the ContinuityApp API. We support this kind of authentication just for testing purposes and to speed up you development time, but we strongly encourage you to invest some efforts into adopting OAuth2 for your production environments.

API Key can be found at Your Apps page. API Key won't be provided in clear, and you will be required to re-create it every time you will loose it.

$ curl -i -u 'marco@continuityapp.com:<api_key>' https://v1.continuityapp.ws/whoami

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept
Server: ContinuityApp Web Services
Content-Length: 48
Date: Fri, 08 Feb 2013 18:13:08 GMT
Cache-control: private
Connection: close

{"response":{"email":"marco@continuityapp.com"}}

require 'net/https'
http = Net::HTTP.new('https://v1.continuityapp.ws', 443)
http.use_ssl = true
http.start do |http|
    request = Net::HTTP::Get.new('/whoami')
    request.basic_auth 'marco@continuityapp.com', '<api_key>'
    response = http.request(request)
    response.value
    puts response.body
end

JSON-P Callbacks

All the GET based endpoints (but the firehose ones) can wrap the JSON response into a function. To take advantage of this feature, you must pass a callback parameter to your request url:

$ curl -i https://v1.continuityapp.ws/whoami?oauth_token=<access_token>&callback=my_json_function

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept
Server: ContinuityApp Web Services
Content-Length: 48
Date: Fri, 08 Feb 2013 19:03:02 GMT
Cache-control: private
Connection: close

my_json_function({"response":{"email":"marco@continuityapp.com"}})

ContinuityApp IDs, JSON, Javascript and other languages

We use Twitter Snowflake to generate Unique IDs across all our services. All the ContinuityApp IDs are rapresented as 64 bits integers, but since Javascript and other languages cannot support numbers with more than 53-bits, we are serving our IDs as Integers and Strings (identified by a _str suffix). If your language or parser can't correctly handle 64 bits Integers use the String-rapresented IDs.

{"response":{"id": 123456789123456789, "id_str": "123456789123456789"}}

Errors

ContinuityApp API uses HTTP response codes to indicate errors, plus a json response with a message.

Valid API requests will reply with a "response" root key in the JSON body:

{"response":{"email":"marco@continuityapp.com"}}

Bogus API requests will reply with a "error" root key in the JSON body. If the error can be related to a provided field, the bogus field will be indicated, otherwise the generic field will be used:

{"error":{"email":["already_taken"]}}
{"error":{"generic":["resource_not_found"]}}

Errors descriptions are expressed in a "short" form. This is the possible combination of HTTP Error code plus error message, and their descriptions.

Eventual specific or additional errors can be found into API endpoints documentation pages.