La plateforme AWT

Notre API privée vous donne la possibilité d'accéder à l'ensemble des données et méthodes que nous utilisons sur nos applications et notre site web.

Se connecter

S'enregistrer

Commencez par enregistrer votre application pour obtenir vos données d'accès à l'API de l'Agence Wallonne des Télécommunications. Soyez certain d'utiliser un compte avec un mot de passe suffisamment sécurisé pour exploiter ces données d'accès. Si vous développez une application pour le compte d'une entreprise, veuillez à obtenir toutes les autorisations nécessaires au préalable. Étant donné que vous n'êtes pas limité quant au nombre de jeux d'accès que vous pouvez créer, n'hésitez pas à en créer autant que nécessaire. Vous pourriez par exemple, en créer un réservé à votre environnement de développement, et un autre pour la production. Dans le cadre de OAuth, votre consumer key obtenue lors du processus d'enregistrement est ici votre client id, et votre secret est ici votre client secret.

Jeton d'accès

Les jetons d'accès permettent à votre application de faire des requêtes à l'API de l'Agence Wallonne des Télécommunications pour le compte d'un utilisateur. Chaque jeton d'accès est unique à chaque utilisateur dans le cadre de chaque "client id" différent. Les jetons d'accès n'expirent pas, mais ils sont susceptibles d'être révoqués par l'utilisateur. Si votre application ne requiert pas l'utilisation de l'API pour le compte d'un utilisateur, vous pouvez directement passer à l'Accès sans jeton.

Requêtes

Une fois que vous avez un jeton d'accès, il est très facile d'utiliser l'ensemble des points terminaux, simplement en ajoutant oauth_token=JETON_ACCES à vos requêtes GET ou POST.

https://api.awt.be/v1/organismes
	?oauth_token=JETON_ACCES

C'est aussi simple que ça.

Authentification

...

Accès sans jeton

Certains de nos points terminaux ne requièrent pas de jeton d'accès, ce qui signifie que vous n'avez pas besoin d'authentifier un utilisateur pour y accéder. Pour faire une requête sans jeton, spécifiez votre client id et votre client secret au lieu d'un oauth_token dans l'URL de la requête.

https://api.awt.be/v1/organismes
	?client_id=CLIENT_ID
	&client_secret=CLIENT_SECRET

Pour connaître le niveau de permission requis pour accéder aux ressources de l'API, consultez la documentation des points terminaux.

Notes sur OAuth2

L'intégration d'OAuth utilisée par l'API de l'AWT permet de faire passer votre client secret en clair, sans nécessité de signer vos requêtes. Cette particularité est rendue possible par l'utilisation obligatoire de HTTPS. Aucune de vos requêtes ne pourra aboutir via HTTP sans SSL.

Notez que l'ensemble de vos requêtes (y compris les requêtes d'autorisation et d'authentification OAuth) devront être dirigées vers le domaine api.awt.be.

Certains librairies OAuth peuvent par défaut envoyer le paramètre access_token au lieu de oauth_token.

Sur Android, vous pourriez rencontrer des problèmes vis à vis du certificat SSL utilisé par l'Agence Wallonne des Télécommunications. En effet, nous utilisons un certificat wildcard, qui n'est pas universellement reconnu par toutes les versions d'Android. Pour plus d'information, veuillez consulter la documentation d'Android relative à ce problème.

Bien que nous forçons pas l'expiration des jetons d'accès OAuth, votre application devrait prévoir cette possibilité à l'avenir. Rappelez-vous également qu'un utilisateur peut choisir de révoquer son autorisation vis à vis de votre application, ce qui rendrait le jeton d'accès correspondant nul.

Réponses et erreurs

Réponses

Toutes les réponses ressembleront, à peu de choses près, à

{
    "meta": {
        "code": 200
        ... errorType, errorDetail ...       
    }
    "response": {
        "resource": {
            ... results ...
        }
    }
}

Le errorType contient des informations destinées aux développeurs. Votre application doit pouvoir afficher des messages d'erreurs appropriés correspondants aux différents code d'erreur repris ci-dessous. Nous sommes susceptibles d'ajouter des types d'erreurs supplémentaires si nécessaire.

La section meta peut également contenir un message destiné à aider les développeurs dans leur processus de débogage.

Pour utiliser JSONP, ajoutez un paramètre callback=xxx à votre requête. Notre API vous répondra avec xxx(response);. Dans le cadre du format JSONP, notre API retourna systématiquement un code 2000 (excepté dans les cas d'erreurs 5xx), pour que le navigateur client puisse renvoyer le résultat à votre code JavaScript. Le code de statut réel peut être obtenu via l'objet code du dictionnaire meta.

Erreurs

Dans la mesure du possible, l'API de l'Agence Wallonne des Télécommunications tente d'utiliser les codes de statut d'en-tête HTTP pour indiquer le cadre général d'une erreur éventuelle. Ce code de statut est répété dans l'objet code du dictionnaire meta.

Code Détails
400 (Bad Request) Un des paramètres est invalide, ou un des paramètres obligatoires est manquant. Cette erreur inclus le cas où aucun jeton d'accès n'est communiqué, ou lorsque l'identifiant d'une ressource et incorrect dans l'URL de la requête.
401 (Unauthorized) Le jeton d'accès fourni est invalide.
403 (Forbidden) L'authentification a réussi mais l'information demandée ne peut être affichée pour des raisons de sécurité ou de vie privée.
404 (Not Found) Le point terminal demandé n'existe pas.
405 (Method Not Allowed) La méthode HTTP (GET, POST, ...) utilisée pour accéder à la ressource est incorrecte.
409 (Conflict) La requête n'a pu aboutir pour des raisons diverses. Utilisez les informations d'erreur fournies pour corriger votre demande.
5xx (Internal Server Error) Les serveurs de l'AWT sont en difficulté. La requête est probablement valide mais devra être retentée plus tard.

En cas d'erreur, des informations additionnelles sont fournis dans l'objet errorType du dictionnaire meta. Celui-ci devrait se retrouver dans le tableau ci-dessous.

errorType Code Explications
invalid_auth 401 Le jeton d'accès n'a pas été fourni ou est invalide.
param_error 400 Un paramètre obligatoire est manquant ou l'un d'eux est mal formaté. Ce type d'erreur est également utilisé si l'identifiant de la ressource est incorrect dans l'URL de la requête.
endpoint_error 404 Le point terminal demandé est introuvable.
not_authorized 403 Bien que l'authentification ait réussi, l'utilisateur n'est pas autorisé à afficher les données demandées pour des raisons de sécurité ou de vie privée.
rate_limit_exceeded 403 Limite de requêtes atteinte pour cette fenêtre temporelle.
server_error * Les serveurs de l'AWT sont en difficulté. Rendez-vous sur status.awt.be pour plus d'informations.
other * Autre type d'erreur rencontré.

Localisation

Vous pouvez spécifier la locale en spécifiant l'en-tête de requête HTTP Accept-Language. Sinon, vous pouvez ajouter le paramètre locale=xx à votre requête, bien que la méthode d'en-tête soit préférable. Nous supportons pour l'instant les locales suivantes : de, en, fr (par défaut) et nl.

Si aucune locale n'est spécifiée, nous utiliserons le français comme langue par défaut pour les éléments géographiques.

Attribution et liens

De la même façon que vous ne citeriez pas quelqu'un sans le mentionner, vous devez créditer l'Agence Wallonne des Télécommunications lorsque vous utilisez nos données.

Utilisation des organismes

...

Attribution visuelle

...

Limitation

L'utilisation de l'API de l'Agence Wallonne des Télécommunications est sujet à des limitations. Ces limites sont relatives à une fenêtre temporelle changeante qui surveille le nombre de requêtes que vous faîtes par heure.

Résumé

Une application peut faire jusqu'à 5 000 requêtes par heure. Bien que nous pensons qu'il s'agisse d'une limite adéquate dans la plupart des cas d'utilisation, vous pouvez toujours demander une augmentation de cette limite.

De manière générale, la limitation suit la règle évoquée ci-dessus. Cependant, certains points terminaux peuvent avoir une limitation différente. Pour obtenir des informations précises et en temps réel du statut de la limitation appliquée, vous pouvez toujours consulter l'en-tête HTTP X-RateLimit-Remaining et X-RateLimit-Limit des réponses de l'API.

Augmentation

Les limitations de votre application peuvent être augmentées ou levées sur demande. Si votre application a besoin de faire plus de requêtes par heure, veuillez nous contacter à l'adresse api@awt.be et nous fournir les informations reprises ci-dessous. Votre demande ne sera pas traitée à moins de nous fournir l'ensemble de ces renseignements.

Informations
Le nom de votre application, une description de ce que votre application fait, votre client id, ainsi qu'une breve justification de l'augmentation demandée.
Utilisation
Quels sont les points terminaux que vous utilisez le plus, et à quelle fréquence les sollicitez-vous ? Veuillez également à nous fournir une explication quant à la manière dont vous utilisez les données fournies. Nous utiliserons ces renseignements pour être certain que votre utilisation rendre dans le cadre de notre Politique ainsi que nos Conditions d'utilisation. Ces informations nous permettent également de vérifier que votre utilisation de l'API est optimale et qu'elle évite des appels inutiles.
Attribution et liens
Envoyez-nous des captures d'écran de votre application, et plus particulièrement des endroits où vous utilisez nos données. Ces captures doivent mettre en évidence que vous créditez de manière appropriée l'Agence Wallonne des Télécommunications. Si votre application est disponible et qu'il nous est possible de l'éprouver à des fins de tests, c'est encore mieux.
Mise en cache
Quelles sont les informations que vous mettez en cache et à quelle fréquence les rafraichissez-vous ? Utilisez la mise en cache dans votre application afin d'éviter les appels répétitifs et inutiles à notre API.

Politiques

En tant que développeur, vous avez une responsabilité tant éthique que légale lorsque vous accéder aux ressources proposées par l'API de l'Agence Wallonne des Télécommunications.

Rétention

Actualisez vos données régulièrement

Vous êtes libre de mettre en cache les données de l'Agence Wallonne des Télécommunications de manière à améliorer les performances de votre application, mais nous avons des restrictions spécifiques quant à la durée maximale de cette mise en cache.

  • Aucune donnée ne peut être conservées plus de 30 jours sans être actualisée
  • Les données à caractères privé ne peuvent être stockées pendant plus de 3 heures

Vie privée

Respectez la vie privée des personnes

Votre application doit respecter les règles étiquetées dans votre Politique de confidentialité. Soyez explicite dans votre politique à propos de la manière dont vous utilisez, stockez, et divulguer les informations fournies par l'Agence Wallonne des Télécommunications.

Attribution

Créditez l'AWT

Si votre application utilise notre plateforme, vous devez créditer l'Agence Wallonne des Télécommunications comme étant la source de vos données.

Limitation

L'utilisation de notre API est sujette à des limitations. Consultez la section reprenant les conditions complètes de ces limites.