Limiter les appels vers un plan d'une API (quota-limiter)

Le quota-limiter est une option qui permet de définir, pour un plan d'une API, une limite du nombre d'appels qu'un client peut effectuer sur une période également définie.

Problématique {#problématique}

La limite de consommation d’une API (quotalimiter) est exprimée en nombre de requêtes par unité de temps. Si la durée d’une minute, d’une heure, d’un jour ou d’une semaine sont une évidence, il n’en est pas de même pour les autres durées selon l’instant où on débute le décompte de la période. Ainsi, pour un mois nous comptons entre 28 et 31 jours, un bimestre entre 59 et 62 jours, un trimestre entre 89 et 92 jours, un quadrimestre entre 120 et 123 jours, un semestre entre 181 et 184 jours et une année 365 ou 366 jours.

Réflexions {#réflexions}

Ainsi, pour éviter de léser le client qui contracterait pour une durée et qui ne pourrait aller au bout de son quota dans certains cas, nous avons décidé de partir sur les durées minimales. Dans le cadre de la reconduction tacite d’un contrat, cela revient à renouveler plus tôt le quota donc, relativement, à offrir un plus gros quota au client.

Sur la base d'une consommation de 10 000 requêtes / mois :

• Si on partait avec une durée moyenne de 30 jours pour un mois, le client ne pourrait consommer d’API le 31ème jour des mois qui ont 31 jours même s'il lui reste du crédit.
• A l’inverse si on partait avec une durée de 31 jours pour un mois, en février le client perdrait 3 jours de consommation.
• La solution est de donc de partir sur la durée minimum d’une période, 28 jours pour le mois donc, et de reconduire tacitement le quota dès expiration de la période. Ainsi le client a 28 jours pour consommer son quota (10 000 requêtes) et dès le lendemain il a de nouveau 10 000 requêtes pour les 28 prochains jours.
• Cette logique s’applique pour les durées des mois, trimestres, semestres et années.

A noter que cet aspect est décorrélé de la facturation, qui elle, peut être réalisée le 10 de chaque mois par exemple.

Durées retenues {#durées-retenues}

Durées exprimées en seconde pour la clé quotaTime :

• seconde : 1
• minute : 60
• heure : 3 600
• jour : 86 400
• semaine : 604 800
• mois : 2 419 200
• bimestre : 5 097 600
• trimestre : 7 689 600
• quadrimestre : 10 368 000
• semestre : 15 638 400
• année : 31 536 000

Cas d'usages

La fonctionnalité Quota-Limiter est notamment utilisée par les APIs suivantes :

• API Adviz CA-Tel v1
• API Adviz CA-Postale
• API Adviz Contrôle Mail
• API Géoloc Inversée
• API Code de la route v1

Principe de fonctionnement

Quota-Limiter simple

Données à renseigner {#données-à-renseigner}

L'API déclare dans son raccordement les données relatives au Quota-Limiter sous le namespace quotaLimiter dans les données relatives au plan. Les attributs du namespace quotaLimiter sont les suivants :

• quotaTime (number) : Durée de la période (en secondes).

• quotaCount (number) : Nombre d'appels possibles pendant la période définie par quotaTime

Configuration dans le raccordement du plan de l'API

- type: plan
  value:
    name: Plan 10K/day
    privacy: private
    ...
    quotaLimiter:
      quotaTime: 86400
      quotaCount: 10000   

Quota-Limiter avec webhook

Données complémentaires à renseigner {#données-complémentaires-à-renseigner}

Le fournisseur de l'API peut souhaiter recevoir une notification par seuils sur un webhook lui appartenant. Dans ce cas, les seuils d'alerte doivent être renseignées dans le plan et l'URL de son webhook dans l'extra de l'API.

• thresholds (number[]) : Seuils auxquels le fournisseur d'API reçoit une notification

• webhook (url) : Adresse URL du webhook sur lequel les notifications seront envoyées

• intoRequestLifeCycle (boulean) : paramètre optionnel réservé à l'usage de l'équipe Okapi. Force l'API gateway à attendre le retour du webhook. Par défaut, sa valeur est "false". A ne pas renseigner dans les usages de production.

Le premier seuil renseigné dans le tableau thresholds sera affiché en "Forfait" sur le plan. L'ordre des seuils suivants n'a pas d'importance. Chaque atteinte de seuil déclenchera l'envoi d'une notification sur le webhook. S'il n'y a pas de seuil renseigné, la ligne "Forfait" ne n'affichera pas sur le plan.

Configuration dans le raccordement du plan de l'API

- type: api
  value:
    name: My Api
    urlContext: monapi
    version: '1'
    extra:
      webhook:
        url: https://foo.com/bar      
- type: plan
  value:
    name: Plan 10K/day
    privacy: private
    ...
    quotaLimiter:
      quotaTime: 86400
      quotaCount: 10000
      thresholds: [1000, 100, 5000, 500, 10000]