Netwo API

Introduction

Netwo - API

Accès à l'API

l'URL de l'API est https://api.netwo.io/api/v1/{ressource}, toutes les requêtes doivent utiliser HTTPS. L'HTTP n'est pas accepté.

L'API Netwo s'appuie sur le standard REST et supporte les verbes HTTP standards, ainsi les requêtes et les réponses sont toutes au format JSON.
L'entête HTTP content-type doit être systématiquement défini et contenir application/json

Authentification

L'api Netwo utilise une clé d'API pour authentifier les requêtes. Celle-ci doit être transmise vie l'entête HTTP x-api-key.

Pour obtenir une clé d'accès à l'API, merci d'en faire la demande par e-mail à l'adresse [email protected]

Cette clé est associée à un ou plusieurs roles pour un ou plusieurs acteurs (tenant) c'est pourquoi il est nécessaire de communiquer l'identifiant (slug) de l'acteur au nom de qui on veut agir via l'entête x-actor-slug

Par conséquent les entêtes HTTP suivants doivent être envoyés à chaque requête,

content-type:application/json
x-actor-slug:[ACTOR_SLUG]
x-api-key:[API_KEY]

Test d'implémentation

Il est possible d'utiliser l'API en mode test afin de ne pas affecter vos données de production.
L'ajout de l'entête HTTP x-realm=test et l'utilisation d'une clé d'API dédiée permet de consommer l'API en mode test.

Rate limiting

Les appels aux endpoints de l'API sont limités en nombre d'appel.
Cette limite varie selon la route appelée.

Les entêtes HTTP suivant permettent de donner des infomations quant aux limites appliquées et l'encours de consommation.

Entête HTTP Description Exemple
x-ratelimit-limitla valeur "100" indique le nombre d'appels permis sur la période, "w=60" indique la période en seconde100, 100;w=60
x-ratelimit-remainingNombre d'appels restant sur la période95
x-ratelimit-resetDurée en seconde avant la fin de la période18

Voir RFC

La majorité des routes sont limitées à 100 appels par minute.

Conventions

Filtres

Certaines routes permettent de filtrer les résulats selon les conditions spécifiées par les opérateurs >=, <=, > et < décrits dans le tableau suivant:

OpérateurMot cléExemple
>=gteamount >= 10 -> /endpoint?amount=10.gte
<=lteamount <= 10 -> /endpoint?amount=10.lte
>gtamount > 10 -> /endpoint?amount=10.gt
<ltamount < 10 -> /endpoint?amount=10.lt

Tri

Certaines routes permettent le tri des résultats sur un attribut en particulier en ajoutant le paramètre sort_by=[nom de l'attribut].[asc|desc]

Par exemple, pour trier les résultats selon la valeur du débit descendant :

https://api.netwo.io/api/v1/endpoint?sort_by=debit.desc 

Liste de valeurs en paramètres de la requête

Pour passer les valeurs ftto et sdsl d'un tableau nommé infrastructure_type en paramètre, le format est le suivant :

https://api.netwo.io/api/v1/endpoint?infrastructure_type[]=ftto&infrastructure_type[]=sdsl 

Erreurs - Codes HTTP

GET
Code HTTPDescription
200Succès
401Utilisateur non connecté
403Accès à la ressource non autorisé
404La ressource n'existe pas
5xxErreur interne
POST
Code HTTPDescription
201Entité créée avec succès
401Utilisateur non connecté
403Création de cette ressource non autorisée
5xxErreur interne
PATCH
Code HTTPDescription
201Entité créée avec succès
401Utilisateur non connecté
403Modification de cette ressource non autorisée
5xxErreur interne
DELETE
Code HTTPDescription
201Entité créée avec succès
401Utilisateur non connecté
403Suppression de cette ressource non autorisée
5xxErreur interne