The more you commit, the less you pay!

Save up to 15% on Dedibox servers with a 36-month commitment, plus free installation costs. Prefer a shorter commitment? Get a 5% discount with a 12-month plan!

Order my Dedibox now!

Scaleway Dedibox Online.net

API

Documentation

Overview

Online by Scaleway exposes a public REST API for some operations. The base URL for all calls is https://api.online.net/api/v1.

To use this API, users can authenticate using their private API token, or with applications that support OAuth2’s three-legged authentication.

Implementation details

  • Methods are grouped by namespaces (e.g. "server", "user").
  • Supported HTTP verbs are GET, POST, PUT, and DELETE.
  • Unless specified otherwise in the method's documentation, all successful API calls return an HTTP code 200 with a JSON object.
  • Errors are returned with an HTTP code 4XX (such as 400 or 403), a JSON object with properties "error" (an error message) and "code" (optional, an integer).
  • The API sends ETag headers and supports the If-None-Match header.
  • Dates are formatted according to the Javascript method date.toJSON.
  • Unless specified otherwise, all API methods require authentication.
  • For debug purposes only, you can get a pretty-printed JSON object by sending the header X-Pretty-JSON: 1.

API methods

Example calls

Here are some example calls, using cURL:

Getting the current user's profile:

Show/hide example

curl -X GET -H "Authorization: Bearer your_api_token" "https://api.online.net/api/v1/user"
HTTP/1.1 200 OK
Content-Type: application/json
etag: b6fa8159e3fb79b2a86aa8302889c58b4d055561
date: Fri, 12 Jul 2013 12:34:56 GMT

{"id":99999,"login":"SuperDupont1789","email":"superdupont1789@free.fr","first_name":"Super","last_name":"Dupont","company":"L'anti-AntiFrance"}

Getting a list of available rescue images for a server:

Show/hide example

curl -X GET -H "Authorization: Bearer your_api_token" "https://api.online.net/api/v1/server/rescue_images/88888"
HTTP/1.1 200 OK
Content-Type: application/json
etag: 3de059c70fd2df09dc89b6867cc994a548dc4d1b
date: Fri, 12 Jul 2013 12:45:43 GMT

["ubuntu-12.04_amd64","ubuntu-10.04_i386","winpe-3.0_amd64","winpe-3.0_i386"]

Code samples

Here are some code samples to show diverse uses of our API:

<?php

// note: error handling is left as an exercise for the reader
function call_online_api($token, $http_method, $endpoint, $get = array(), $post = array())
{
    if (!empty($get)) {
        $endpoint .= '?' . http_build_query($get);
    }

    $call = curl_init();
    curl_setopt($call, CURLOPT_URL, 'https://api.online.net/api/v1' . $endpoint);
    curl_setopt($call, CURLOPT_HTTPHEADER, array('Authorization: Bearer ' . $token, 'X-Pretty-JSON: 1'));
    curl_setopt($call, CURLOPT_RETURNTRANSFER, true);

    if ($http_method == 'POST') {
        curl_setopt($call, CURLOPT_POST, true);
        curl_setopt($call, CURLOPT_POSTFIELDS, http_build_query($post));
    }

    return curl_exec($call);
}

$token = YOUR_API_TOKEN;

$user_info = call_online_api($token, 'GET', '/user');
echo $user_info;

$failovers = call_online_api($token, 'GET', '/server/failover');
echo $failovers;

// edit a failover IP
$post = array(
    'source' => '10.0.0.42',
    'destination' => '10.0.0.1',
);
$move_failover = call_online_api($token, 'POST', '/server/failover/edit', null, $post);
var_export($move_failover);

Using slumber:

import slumber, requests

api_session = requests.session()
api_session.headers['Authorization'] = 'Bearer YOUR_API_TOKEN'

api = slumber.API('https://api.online.net/api/v1', session=api_session)

user_info = api.user.info.get()
print user_info

failovers = api.server.failover.get()
print failovers

# edit a failover IP
move_failover = api.server.failover.edit.post({
    'source': '10.0.0.42',
    'destination': '10.0.0.1'
})
print move_failover

Authentication

Calls that require authentication expect an HTTP header Authorization bearing a token, using the following format:

Authorization: Bearer your_api_token

This token can either be your private API token, or a token obtained using OAuth2's three-legged authentication.

Authentication for applications

First, you must create an app.

Once you have created an app, you are provided a client_id and client_secret that you will use for the authentication process.

Which authentication process should you use?

Workflow for websites or client applications

This authentication process uses three-legged OAuth2.

The following URLs are used in this process:

  • authorize endpoint: /oauth/v2/auth
  • token endpoint: /oauth/v2/token

Note: if your application is not a website, you will have to make the user do these steps in a web view (e.g. UIWebView on iOS, WebView on Android…).

Full workflow

  1. Your application redirects the user to Online.net's authorize endpoint, with the following query string parameters:

    • client_id: your app's client_id
    • redirect_uri: one of your application's redirect URLs
    • response_type: use the value "code"
    • state: an arbitrary string that will be returned to your application, to help you check against CSRF
    Example URL for authorization:
    https://console.online.net/oauth/v2/auth?client_id=42_424242&redirect_uri=https://your-app.tld/online_api&response_type=code&state=yeahponies

  2. The user chooses to authorize your application.

  3. The user gets redirected to the URL you specified using the parameter redirect_uri, with the following query string parameters:

    • code: the code that you will use to get a token
    • state: the same value that you sent earlier

  4. Using the value of code, your application makes a direct POST request (not in the user's browser) to the token endpoint, with the following parameters:

    • client_id
    • client_secret
    • code: the value that you received earlier
    • redirect_uri: one of your application's redirect URLs
    • grant_type: use the value "authorization_code"
    Example cURL call to obtain an access token:
    curl -X POST "https://console.online.net/oauth/v2/token" -d "client_id=42_424242&client_secret=123456&code=986a9e6d90e&redirect_uri=https://your-app.tld/online_api&grant_type=authorization_code"

  5. If everything is correct, the access token is returned as a JSON object with the following properties:

    • access_token
    • expires_in: token validity period, in seconds
    • token_type: "Bearer"

  6. Your application stores the access token and uses it for the user's subsequent visits.

Workflow for mobile apps

This authentication process uses a variant of OAuth2, tailored for mobile devices.

The following URLs are used in this process:

  • device endpoint: /oauth/v2/device/code
  • verification endpoint: /oauth/v2/device/usercode
  • token endpoint: /oauth/v2/token

Note: you may have to make the user do some steps in a web view (e.g. UIWebView on iOS, WebView on Android…) if you want to do all these steps from the mobile app.

Full workflow

  1. Your application makes a direct request to the device endpoint, with the query string parameter client_id, and obtains a JSON object with authentication data that will be used for the rest of the process.

    Example URL to obtain authentication data:
    https://console.online.net/oauth/v2/device/code?client_id=42_424242
    Example authentication data:
    {
    "device_code": "5b7a15a9ae1bc30f903210dcafb6dff4d893a880",
    "user_code": "fu5rohd4h",
    "interval": 5,
    "expires_in": 1800,
    "verification_url": "https:\/\/console.online.net\/oauth\/v2\/device\/code"
}

  2. Your application asks the user to go to the verification endpoint (provided by verification_url) and to type the code provided by user_code.

  3. Using the value of device_code, every 5 seconds your application starts making direct POST requests to the token endpoint, with the following parameters:

    • client_id
    • client_secret
    • code: the value of device_code
    • grant_type: use the value "http://oauth.net/grant_type/device/1.0"
    Example cURL call to obtain an access token:
    curl -X POST "https://console.online.net/oauth/v2/token" -d "client_id=123_987654&client_secret=4815162342&code=986a9e6d90e&grant_type=http://oauth.net/grant_type/device/1.0"

    Your application will receive an error message until the user has entered the code and authorized the application.

  4. The user enters the code, and then logs in if they aren't logged in yet.

  5. The user chooses to authorize your application, and can then close the browser window.

  6. Your application's call to the token endpoint now returns the access token as a JSON object with the following properties:

    • access_token
    • expires_in: token validity period, in seconds
    • token_type: "Bearer"

  7. Your application stores the access token and uses it for the user's subsequent visits.

Workflow for opensource apps

This authentication process is similar to OAuth2 for mobile devices, with the difference that opensource apps or scripts can not be shipped with a client_secret (since it's meant to remain secret).

The principle here is to get a new set of client_id and client_secret that are bound to the user. You may reuse these credentials by using OAuth2 for mobile devices.

Warning: You should not redistribute the credentials. Usage with another account will display the login of the user who obtained the credentials. E.g. instead of displaying "The most fabulous app" it will display "The most fabulous app (jeanpatrickranu1979)".

The following URLs are used in this process:

  • device endpoint: /oauth/v2/device/code
  • verification endpoint: /oauth/v2/device/usercode
  • credentials endpoint: /oauth/v2/device/credentials
  • token endpoint: /oauth/v2/token

Full workflow

  1. Your application makes a direct request to the device endpoint, with the query string parameters client_id and new_credentials=yes, and obtains a JSON object with authentication data that will be used for the rest of the process.

    Example URL to obtain authentication data:
    https://console.online.net/oauth/v2/device/code?client_id=42_424242&new_credentials=yes
    Example authentication data:
    {
    "device_code": "5b7a15a9ae1bc30f903210dcafb6dff4d893a880",
    "user_code": "fu5rohd4h",
    "interval": 5,
    "expires_in": 1800,
    "verification_url": "https:\/\/console.online.net\/oauth\/v2\/device\/code"
}

  2. Your application asks the user to go to the verification endpoint (provided by verification_url) and to type the code provided by user_code.

  3. Using the value of device_code, every 5 seconds your application starts making direct requests to the credentials endpoint, with the following query string parameters:

    • client_id
    • code: the value of device_code

    Your application will receive an error message until the user has entered the code and authorized the application.

  4. The user enters the code, and then logs in if they aren't logged in yet.

  5. The user chooses to authorize your application, and can then close the browser window.

  6. Your application's call to the credentials endpoint now returns a JSON object with the following properties:

    • client_id: a new client_id that is bound to the user
    • client_secret

    Your application stores these values and will use them for later requests.

  7. Using the value of device_code, your application makes a direct POST request to the token endpoint, with the following parameters:

    • client_id: the value of client_id provided by the call to the credentials endpoint
    • client_secret: the value of client_secret provided by the call to the credentials endpoint
    • code: the value of device_code
    • grant_type: use the value "http://oauth.net/grant_type/device/1.0"
    Example cURL call to obtain an access token:
    curl -X POST "https://console.online.net/oauth/v2/token" -d "client_id=123_987654&client_secret=4815162342&code=986a9e6d90e&grant_type=http://oauth.net/grant_type/device/1.0"

  8. Your application stores the access token and uses it for the user's subsequent visits.

List of numeric error codes

In addition to the HTTP error code, errors come with a message and a numeric code. The error message is meant to be human-readable, while the numeric codes should be used by your application.

-1 Internal error
1 Missing parameter
2 Bad parameter value
3 Unknown method
4 Method not allowed
5 Bad request
6 Not implemented yet
7 Resource not found
8 Resource unreachable
9 Permission denied
10 Action already done
11 User has unpaid invoices
12 Too many requests
13 Resource creation pending
16 Resource busy
17 Conflict

Contracts - Legal notices - Privacy Policy - Security Measures - Cookie Settings
Copyright © 1999-2024 - Scaleway SAS - BP 438 - 75366 Paris CEDEX 08 - RCS Paris B 433 115 904