Netwo API

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 "100" indique le nombre d'appels permis sur la période, "w=60" indique la période en seconde	`100, 100;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 à 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é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