Introduction

The 30suns API is organized around REST. The API is designed to have simple, predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. Please remember that you should never expose your secret API key in any public website’s client-side code. JSON will be returned in all responses from the API, including errors.

To make the 30suns API as explorable as possible, accounts are automatically assigned an API key which you can retrieve by clicking on the API Keys link from within your account dashboard. You can invalidate a key and generate a new key by clicking the Generate API Key button.

Authentication

You authenticate to the 30suns API by providing your API keys in the request via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests. In the examples that follow you should substitute your API Key for the string APIKEY.

Errors

30suns uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with 30suns’ servers.

Services

Get a list of Services

Retrieve a list of service associate with your account by sending an authenticated GET request to the services endpoint.

$ curl https://30suns.com/api/services/ -u APIKEY: 
#!/usr/bin/env ruby
require 'net/https'
http = Net::HTTP.new('30suns.com', 443)
http.use_ssl = true
http.start do |http|
request = Net::HTTP::Get.new('/api/services/')
request.basic_auth 'APIKEY', ''
response = http.request(request)
response.value
puts response.body
end
<?php
    $key = 'APIKEY';
    $ch = curl_init();
    curl_setopt( $ch, CURLOPT_URL, 'https://30suns.com/api/services/');
    curl_setopt( $ch, CURLOPT_HEADER, false );
    curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt( $ch, CURLOPT_USERPWD, $key.':');
    curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, 'GET' );
    $response = curl_exec( $ch );
    print_r( $response, true );
?>

Example Response

{"object":"list","url":"services","count":1,"data":[{"object":"service","id":"website"}]}

Events (incident reports)

Create a new Event

Log an incident report by creating an Event object and sending an authenticated POST request to the events endpoint.

The level parameter has four possible values, ok (Service is operating normally), warning(Performance issue), minus (Service disruption) or info (Informational message).

The service parameter is constructed from the name of the service when you create it from the dashboard. If you are unsure what the correct service names for your services are you can retrieve them using the Services GET request documented previously.

curl https://30suns.com/api/events/ \
   -u APIKEY: \
   -d title="[RESOLVED] Increased API Error Rates" \
   -d level=ok \
   -d service=website \
   -d "description=The API errors have been resolved." \
<?php
    $key = 'APIKEY';
    $data = array(
        'title'            => '[RESOLVED] Increased API Error Rates',
        'level'            => 'ok',
        'service'          => 'website',
        'description'      => 'The API errors have been resolved.'
    );
    $ch = curl_init();
    curl_setopt( $ch, CURLOPT_URL, 'https://30suns.com/api/events/' );
    curl_setopt( $ch, CURLOPT_HEADER, false );
    curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt( $ch, CURLOPT_USERPWD, $key.':');
    curl_setopt( $ch, CURLOPT_POST, count($data));
    curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
    $response = curl_exec( $ch );
    print_r( $response, true );
?>

Example Response

{"object":"event","created":true}

Have you developed some code to work with 30suns API? Contact us if you’d like us to consider adding it and expanding the above reference.