API

Online by Scaleway expose une API publique REST pour quelques opérations. L'URL de base pour tous les appels est https://api.online.net/api/v1.

Pour utiliser cette API, les utilisateur(trice)s peuvent s'identifier à l'aide de leur token API privé, ou avec des applications qui supportent l'authentification OAuth2.

Les méthodes sont regroupées par espace de nom (par exemple "server", "user").
Les verbes HTTP supportés sont GET, POST, PUT et DELETE.
Sauf quand la documentation spécifie un cas particulier, tous les appels d'API sans erreur retournent un code HTTP 200 avec un objet JSON.
Les erreurs sont retournées avec un code HTTP 4XX (par exemple 400 ou 403), et un objet JSON avec les propriétés "error" (message d'erreur) et "code" (un entier, optionnel).
L'API envoie des en-têtes ETag et gère l'en-tête If-None-Match.
Les dates sont formattées comme dans la méthode Javascript date.toJSON.
Sauf quand c'est spécifié, toutes les méthodes d'API requièrent l'authentification.
Pour le déboggage seulement, vous pouvez obtenir un formattage plus lisible de l'objet JSON en envoyant l'en-tête X-Pretty-JSON: 1.

Voici quelques exemples d'appels, en utilisant cURL:

Obtenir les infos du compte identifié :

Afficher/masquer l'exemple

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"}

Obtenir une liste des images de rescue disponibles pour un serveur :

Afficher/masquer l'exemple

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"]

Voici quelques exemples de code avec différents usages de l'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);

En utilisant 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

Les appels nécessitant l'authentification attendent un en-tête HTTP Authorization comportant un token, selon le format suivant :

Authorization: Bearer your_api_token

Ce token peut être votre token d'API privé, ou un token obtenu via l'authentification OAuth2.

D'abord, vous devez créer une appli.

Une fois que vous avez créé une appli, vous obtenez un client_id et un client_secret à utiliser pour le processus d'authentification.

Quel processus d'authentification devriez-vous utiliser ?

Si votre application est un site web : OAuth2 three-legged.
Si votre application est une appli mobile : OAuth2 pour mobiles.
Si votre application est une app opensource ou un script : OAuth2 pour apps opensource.

Workflow pour les sites web ou les applications clientes

Ce processus d'authentification utilise la version three-legged d'OAuth2.

Les URL suivantes sont utilisées dans ce processus :

URI autorisation : /oauth/v2/auth
URI token : /oauth/v2/token

Note : si votre application n'est pas un site web, vous devrez faire effectuer ces étapes à l'utilisateur(trice) dans une vue web (par exemple UIWebView pour iOS, WebView pour Android…).

Workflow complet

Votre application redirige l'utilisateur(trice) vers l'URI autorisation d'Online.net, avec les paramètres GET suivants :
- client_id: le client_id de votre appli
- redirect_uri: une des URL de redirection de votre application
- response_type: utilisez la valeur "code"
- state: une chaîne arbitraire qui sera retournée à votre application, pour vous aider à éviter les CSRF
Exemple d'URL pour l'autorisation :
```
https://console.online.net/oauth/v2/auth?client_id=42_424242&redirect_uri=https://your-app.tld/online_api&response_type=code&state=yeahponies
```
L'utilisateur(trice) choisit d'autoriser votre application.
L'utilisateur(trice) est redirigé(e) vers l'URL que vous avez spécifiée avec le paramètre redirect_uri, avec les paramètres suivants :
- code: le code que vous allez échanger contre un token
- state: la valeur que vous avez envoyée précédemment
En utilisant la valeur de code, votre application fait une requête POST directe (pas dans la navigateur de l'utilisateur(trice)) vers l'URI token, avec les paramètres suivants :
- client_id
- client_secret
- code: la valeur reçue précédemment
- redirect_uri: une des URL de redirection de votre application
- grant_type: utilisez la valeur "authorization_code"
Exemple d'appel cURL pour obtenir un 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"
```
Si tout est correct, le token est retourné dans un objet JSON avec les propriétés suivantes :
- access_token
- expires_in: période de validité du token, en secondes
- token_type: "Bearer"
Votre application stocke le token d'accès et l'utilise pour les visites suivantes de l'utilisateur(trice).

Workflow pour les applis mobiles

Ce processus d'authentification utilise une variante d'OAuth2, adaptée pour les mobiles.

Les URL suivantes sont utilisées dans ce processus :

URI device : /oauth/v2/device/code
URI vérification : /oauth/v2/device/usercode
URI token : /oauth/v2/token

Note : vous aurez à faire faire certaines étapes dans une vue navigateur (exemple : UIWebView pour iOS, WebView pour Android…) si vous voulez effectuer toutes les étapes sans sortir de l'appli mobile.

Workflow complet

Votre application fait une requête directe sur l'URI device, avec le paramètre GET client_id, et obtient un objet JSON avec les données d'authentification qui seront utilisés pour le reste du process.

Exemple d'URL pour obtenir les données d'authentification :
```
https://console.online.net/oauth/v2/device/code?client_id=42_424242
```
Exemple de données d'authentification :
```
{
    "device_code": "5b7a15a9ae1bc30f903210dcafb6dff4d893a880",
    "user_code": "fu5rohd4h",
    "interval": 5,
    "expires_in": 1800,
    "verification_url": "https:\/\/console.online.net\/oauth\/v2\/device\/code"
}
```
Votre application demande à l'utilisateur(trice) d'aller sur l'URI de vérification (fournie par verification_url) et d'y taper le code fourni par user_code.
En utilisant la valeur de device_code, toutes les 5 secondes votre application commence à faire des requêtes POST directes à l'URI token, avec les paramètres suivants :
- client_id
- client_secret
- code: la valeur de device_code
- grant_type: utilisez la valeur "http://oauth.net/grant_type/device/1.0"
Exemple d'appel cURL pour obtenir un 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"
```
Votre application recevra un message d'erreur tant que l'utilisateur(trice) n'aura pas entré le code et autorisé l'application.
L'utilisateur(trice) entre le code, et se connecte s'il(elle) n'est pas déjà connecté(e).
L'utilisateur(trice) choisit d'autoriser votre application, et peut alors fermer la fenêtre de navigateur.
L'appel de votre application à l'URI token retourne maintenant le token dans un objet JSON avec les propriétés suivantes :
- access_token
- expires_in: période de validité du token, en secondes
- token_type: "Bearer"
Votre application stocke le token d'accès et l'utilise pour les visites suivantes de l'utilisateur(trice).

Workflow pour les applis opensources

Ce processus d'authentification est similaire à OAuth2 pour mobiles, avec pour différence que les applis opensource ou les scripts ne peuvent pas être distribués avec un client_secret (puisqu'il est censé rester secret).

Le principe ici est d'obtenir un client_id et un client_secret liés à l'utilisateur(trice). Vous pourrez alors réutiliser ces identifiants avec le workflow OAuth2 pour mobiles.

Avertissement : Vous ne devez pas redistribuer les identifiants. L'usage des identifiants avec un autre compte affichera le login de l'utilisateur(trice) qui a obtenu les identifiants. Exemple : au lieu d'afficher simplement "L'appli la plus fabuleuse", on affichera "L'appli la plus fabuleuse (jeanpatrickranu1979)".

Les URL suivantes sont utilisées dans ce processus :

URI device : /oauth/v2/device/code
URI vérification : /oauth/v2/device/usercode
URI identifiants : /oauth/v2/device/credentials
URI token : /oauth/v2/token

Workflow complet

Votre application fait une requête directe sur l'URI device, avec les paramètres GET client_id et new_credentials=yes, et obtient un objet JSON avec les données d'authentification qui seront utilisés pour le reste du process.

Exemple d'URL pour obtenir les données d'authentification :
```
https://console.online.net/oauth/v2/device/code?client_id=42_424242&new_credentials=yes
```
Exemple de données d'authentification :
```
{
    "device_code": "5b7a15a9ae1bc30f903210dcafb6dff4d893a880",
    "user_code": "fu5rohd4h",
    "interval": 5,
    "expires_in": 1800,
    "verification_url": "https:\/\/console.online.net\/oauth\/v2\/device\/code"
}
```
Votre application demande à l'utilisateur(trice) d'aller sur l'URI de vérification (fournie par verification_url) et d'y taper le code fourni par user_code.
En utilisant la valeur de device_code, toutes les 5 secondes votre application commence à faire des requêtes directes à l'URI identifiants, avec les paramètres GET suivants :
- client_id
- code: la valeur de device_code
Votre application recevra un message d'erreur tant que l'utilisateur(trice) n'aura pas entré le code et autorisé l'application.
L'utilisateur(trice) entre le code, et se connecte s'il(elle) n'est pas déjà connecté(e).
L'utilisateur(trice) choisit d'autoriser votre application, et peut alors fermer la fenêtre de navigateur.
L'appel de votre application à l'URI identifiants retourne maintenant un objet JSON avec les propriétés suivantes :
- client_id: a new client_id that is bound to the user
- client_secret
Votre application stocke ces valeurs et les utilisera pour les requêtes futures.
En utilisant la valeur de device_code, votre application fait une requête POST directe à l'URI token, avec les paramètres suivants :
- 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: la valeur de device_code
- grant_type: utilisez la valeur "http://oauth.net/grant_type/device/1.0"
Exemple d'appel cURL pour obtenir un 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"
```
Votre application stocke le token d'accès et l'utilise pour les visites suivantes de l'utilisateur(trice).

En plus du code d'erreur HTTP, les erreurs sont retournées avec un message et un code numérique. Le message d'erreur est une indication lisible, tandis votre application ne doit se soucier que des codes numériques.

-1	Erreur interne
1	Paramètre manquant
2	Mauvaise valeur de paramètre
3	Méthode inconnue
4	Méthode non autorisée
5	Mauvaise requête
6	Pas encore implémenté
7	Ressource introuvable
8	Ressource non atteignable
9	Permission refusée
10	Action déjà effectuée
11	L'utilisateur a des factures impayées
12	Trop de requêtes
13	Ressource en cours de création
16	Ressource occupée
17	Conflit

Plus vous vous engagez, moins vous payez !

Documentation

Introduction

Détails d'implémentation

Méthodes d'API

Exemples d'appels

Obtenir les infos du compte identifié :

Obtenir une liste des images de rescue disponibles pour un serveur :

Exemples de code

Authentification

Authentification des applications

Quel processus d'authentification devriez-vous utiliser ?

Workflow pour les sites web ou les applications clientes

Workflow complet

Exemple d'URL pour l'autorisation :

Exemple d'appel cURL pour obtenir un token :

Workflow pour les applis mobiles

Workflow complet

Exemple d'URL pour obtenir les données d'authentification :

Exemple de données d'authentification :

Exemple d'appel cURL pour obtenir un token :

Workflow pour les applis opensources

Workflow complet

Exemple d'URL pour obtenir les données d'authentification :

Exemple de données d'authentification :

Exemple d'appel cURL pour obtenir un token :

Liste de codes d'erreur numériques