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.
Errors | ||
---|---|---|
400 | api_does_not_exists |
The API endpoint you tried to request does not exists. |
401 | unauthorized |
You did not provide authorization information, or it is invalid. |
401 | account_suspended |
The account has been suspended. Please contact our Support. |
402 | payment_required |
The account ended the trial period without providing Billing Information, or has overdue invoices. In both cases you still can act as a collaborator for other projects. |
403 | already_exists |
The resource field has a non-unique value. |
403 | is_blank |
The resource field is required, and cannot be blank. |
403 | invalid_format |
The resource field format is invalid. |
403 | resource_temporary_unavailable |
The resource you are requesting is not available at the moment. You should retry later. |
403 | is_reserved |
The resource is reserved, and cannot be used. |
404 | not_found |
The resource you are looking for cannot be found. |
500 | Internal Server Error | Something went wrong on ContinuityApp's servers. |
Eventual specific or additional errors can be found into API endpoints documentation pages.
comments powered by Disqus