API v2 - acces authentifie

API v2 : acces authentifie a l'observatoire NextHop

Quotas eleves, champs etendus, historique scores illimite. Authentification optionnelle (anonyme aussi supporte). Spec OpenAPI 3.0.

Authentification

Cle API optionnelle

Anonyme = 30 req/min, 7j scores. Avec cle = jusqu'a 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

Telecharger openapi-v2.yaml ->

Migration depuis v1

Quelles differences avec /api/v1 ?

La v1 reste maintenue. La v2 ajoute l'authentification, des quotas eleves, des champs etendus et un endpoint d'usage.

Fonctionnalite

Authentification

Aucune

Optionnelle (X-API-Key)

Pagination /providers

Tout en une page

limit + offset (500 anon, 1000 auth)

Champs etendus

Non

notes_admin, last_audit_date (si cle)

Historique scores

Pas d'endpoint dedie

/scores/history (7j anon, illimite auth)

Commentaires criteres

Non

criteria[k].comment (si cle)

Endpoint /usage

N/A

Suivi quota en temps reel

Quota mensuel

Aucun (rate-limit seul)

10k / 100k / 1M selon tier

Obtenir une cle

Trois etapes 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 pre-rempli. Reponse sous 48h ouvres.

Recevoir la cle

Une cle au format nh_xxxxxxxx.... Sauvegardez-la : elle ne sera plus jamais affichee.

Authentification

Deux methodes pour transmettre la cle

La cle est envoyee dans l'en-tete X-API-Key (recommande) ou dans le query string ?api_key= (pour test rapide en curl). Ni Bearer JWT ni Basic Auth ne sont supportes : ces schemas sont reserves aux APIs internes.

Header HTTP (recommande)

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. Preferez le header en production.

Endpoints v2

Cinq routes

GET/api/v2/providers

Liste paginee des fournisseurs. Champs etendus si cle presente.

Exemple anonyme

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

Exemple authentifie

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

GET/api/v2/providers/{slug}

Detail d'un fournisseur avec criteres scores. Sous-champ comment ajoute si cle.

Exemple anonyme

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

Exemple authentifie

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

GET/api/v2/scores

Scores courants. Parametres : ?sort=score|name &order=asc|desc.

Exemple anonyme

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

Exemple authentifie

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: illimite (param since).

Exemple anonyme

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

Exemple authentifie

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 cle (tier, rate-limit, quota mensuel). Auth requise.

Exemple authentifie

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

Fenetre history

Anonyme

30 req/min

Pas de quota mensuel

7 jours scores/history

Free

60 req/min

10 000 req/mois

Illimite

Pro

600 req/min

100 000 req/mois

Illimite

Enterprise

10 000 req/min

1 000 000 req/mois

Illimite

Headers de reponse

Surveillance live des limites

Chaque reponse authentifiee inclut ces headers (exposes 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 fenetre 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 unifie

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

401 invalid_api_keyCle absente, malformee, revoquee ou expiree.

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

429 rate_limit_exceededTrop de requetes dans la fenetre 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 notifie.

Suivi quota

Endpoint /api/v2/usage

Renvoie en temps reel le tier, le rate-limit, le quota mensuel, l'usage courant et le pourcentage consomme. Pratique pour deconencher un fallback (ex : passer en cache local au-dela 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 cle Hub developpeurs Documentation v1