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-limit | la valeur "200" indique le nombre d'appels permis sur la période, "w=60" indique la période en seconde | 200, 200;w=60 |
x-ratelimit-remaining | Nombre d'appels restant sur la période | 95 |
x-ratelimit-reset | Durée en seconde avant la fin de la période | 18 |
Voir RFC
La majorité des routes sont limitées à 200 appels par minute et 20000 appels par jours.
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érateur | Mot clé | Exemple |
---|---|---|
>= | gte | amount >= 10 -> /endpoint?amount=10.gte |
<= | lte | amount <= 10 -> /endpoint?amount=10.lte |
> | gt | amount > 10 -> /endpoint?amount=10.gt |
< | lt | amount < 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 HTTP | Description |
---|---|
200 | Succès |
401 | Utilisateur non connecté |
403 | Accès à la ressource non autorisé |
404 | La ressource n'existe pas |
5xx | Erreur interne |
POST
Code HTTP | Description |
---|---|
201 | Entité créée avec succès |
401 | Utilisateur non connecté |
403 | Création de cette ressource non autorisée |
5xx | Erreur interne |
PATCH
Code HTTP | Description |
---|---|
201 | Entité créée avec succès |
401 | Utilisateur non connecté |
403 | Modification de cette ressource non autorisée |
5xx | Erreur interne |
DELETE
Code HTTP | Description |
---|---|
201 | Entité créée avec succès |
401 | Utilisateur non connecté |
403 | Suppression de cette ressource non autorisée |
5xx | Erreur interne |
Updated 16 days ago