API v2 - accès authentifié

API v2 : accès authentifié à l'observatoire NextHop

Quotas élevés, champs étendus, historique scores illimité. Authentification optionnelle (anonyme aussi supporté). Spec OpenAPI 3.0.

Authentification

Clé API optionnelle

Anonyme = 30 req/min, 7j scores. Avec clé = jusqu'à 10 000 req/min selon le tier.

Quotas

10k / 100k / 1M mois

Free / Pro / Enterprise. Reset au 1er du mois (champ X-Quota-Reset).

Specification

OpenAPI 3.0 YAML

Télécharger openapi-v2.yaml ->

Migration depuis v1

Quelles différences avec /api/v1 ?

La v1 reste maintenue. La v2 ajoute l'authentification, des quotas élevés, des champs étendus et un endpoint d'usage.

Fonctionnalité

Authentification

Aucune

Optionnelle (X-API-Key)

Pagination /providers

Tout en une page

limit + offset (500 anon, 1000 auth)

Champs étendus

Non

notes_admin, last_audit_date (si clé)

Historique scores

Pas d'endpoint dédié

/scores/history (7j anon, illimité auth)

Commentaires critères

Non

criteria[k].comment (si clé)

Endpoint /usage

N/A

Suivi quota en temps réel

Quota mensuel

Aucun (rate-limit seul)

10k / 100k / 1M selon tier

Obtenir une clé

Trois étapes simples

Choisir un tier

Free (gratuit), Pro (49 EUR HT/mois) ou Enterprise (devis). Voir page Tarifs.

Faire la demande

Via le formulaire de contact avec sujet pré-rempli. Réponse sous 48h ouvrés.

Recevoir la clé

Une clé au format nh_xxxxxxxx.... Sauvegardez-la : elle ne sera plus jamais affichée.

Authentification

Deux méthodes pour transmettre la clé

La clé est envoyée dans l'en-tête X-API-Key (recommandé) ou dans le query string ?api_key= (pour test rapide en curl). Ni Bearer JWT ni Basic Auth ne sont supportés : ces schémas sont réservés aux APIs internes.

Header HTTP (recommandé)

curl -s https://www.nexthop.fr/api/v2/usage \
  -H 'X-API-Key: nh_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'

Query parameter (test rapide)

curl -s 'https://www.nexthop.fr/api/v2/scores?api_key=nh_a1b2c3d4...'

Note : les query strings finissent dans les logs serveur et navigateur. Préférez le header en production.

Endpoints v2

Cinq routes

GET/api/v2/providers

Liste paginée des fournisseurs. Champs étendus si clé présente.

Exemple anonyme

curl -s 'https://www.nexthop.fr/api/v2/providers?limit=100'

Exemple authentifié

curl -s 'https://www.nexthop.fr/api/v2/providers?limit=500' \
  -H 'X-API-Key: nh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

GET/api/v2/providers/{slug}

Détail d'un fournisseur avec critères scorés. Sous-champ comment ajouté si clé.

Exemple anonyme

curl -s https://www.nexthop.fr/api/v2/providers/ovh

Exemple authentifié

curl -s https://www.nexthop.fr/api/v2/providers/ovh \
  -H 'X-API-Key: nh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

GET/api/v2/scores

Scores courants. Paramètres : ?sort=score|name &order=asc|desc.

Exemple anonyme

curl -s 'https://www.nexthop.fr/api/v2/scores?sort=score&order=desc'

Exemple authentifié

curl -s 'https://www.nexthop.fr/api/v2/scores?sort=score&order=desc' \
  -H 'X-API-Key: nh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

GET/api/v2/scores/history

Historique des changements de score. Anon: 7j max. Auth: illimité (param since).

Exemple anonyme

curl -s 'https://www.nexthop.fr/api/v2/scores/history?limit=100'

Exemple authentifié

curl -s 'https://www.nexthop.fr/api/v2/scores/history?since=2025-01-01&limit=5000' \
  -H 'X-API-Key: nh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

GET/api/v2/usageAUTH REQUISE

Stats d'usage de la clé (tier, rate-limit, quota mensuel). Auth requise.

Exemple authentifié

curl -s https://www.nexthop.fr/api/v2/usage \
  -H 'X-API-Key: nh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Quotas par tier

Rate limit + quota mensuel

Tier

Rate limit

Quota mensuel

Fenêtre history

Anonyme

30 req/min

Pas de quota mensuel

7 jours scores/history

Free

60 req/min

10 000 req/mois

Illimité

Pro

600 req/min

100 000 req/mois

Illimité

Enterprise

10 000 req/min

1 000 000 req/mois

Illimité

Headers de réponse

Surveillance live des limites

Chaque réponse authentifiée inclut ces headers (exposés via Access-Control-Expose-Headers pour les SPA) :

X-RateLimit-Limit:      600          # max req/min pour le tier
X-RateLimit-Remaining:  587          # restantes dans la fenêtre courante
X-RateLimit-Reset:      1716462000   # epoch UNIX du reset

X-Quota-Limit:          100000       # quota mensuel
X-Quota-Remaining:      94213        # restantes ce mois
X-Quota-Reset:          2026-06-01T00:00:00.000Z

Codes d'erreur

Format unifié

Une erreur répond avec : { "error": "<code>", "message": "<text>" }. Le quota_exceeded ajoute le champ resets_at.

401 invalid_api_keyClé absente, malformée, révoquée ou expirée.

401 api_key_requiredEndpoint qui exige une clé (ex : /usage).

429 rate_limit_exceededTrop de requêtes dans la fenêtre courante.

429 quota_exceededQuota mensuel atteint. Reset au 1er du mois suivant (champ resets_at).

404 not_foundProvider slug introuvable.

500 internal_errorErreur serveur. Notre monitoring est notifié.

Suivi quota

Endpoint /api/v2/usage

Renvoie en temps réel le tier, le rate-limit, le quota mensuel, l'usage courant et le pourcentage consommé. Pratique pour déconencher un fallback (ex : passer en cache local au-delà de 80%).

{
  "data": {
    "tier": "pro",
    "rate_limit_per_minute": 600,
    "monthly_quota": 100000,
    "current_month_usage": 5787,
    "remaining": 94213,
    "percent_used": 5.8
  },
  "meta": {
    "generated_at": "2026-05-23T12:30:00.000Z"
  }
}

Pour aller plus loin

Spec OpenAPI v2 et liens connexes

openapi-v2.yaml Tarifs et tiers Demander une clé Hub développeurs Documentation v1