Aller au contenu principal

Introduction à l'API Wast-o

L'API publique Wast-o permet d'accéder aux données de collecte de déchets, calendriers, challenges et contenus éditoriaux de manière programmatique.

Client officiel

Pour consommer l'API facilement depuis JavaScript ou TypeScript, utilisez le client officiel : voir Client SDK.

Base URL​

https://api.wast-o.com

Tous les endpoints de l'API publique sont préfixés par /public.

Pagination​

Les listes récentes renvoient :

{
  "data": [],
  "meta": { "page": 1, "pageSize": 20, "total": 0, "totalPages": 0 }
}

Query : page (défaut 1), pageSize (défaut 20, max 100). Quelques routes legacy (ex. GET /public/challenges/:cityId) renvoient encore un tableau brut.

Les exemples fetch ci-dessous lisent souvent const { data } = await response.json().

Authentification​

L'API publique Wast-o ne nécessite pas d'authentification pour la plupart des endpoints. Tous les endpoints sont accessibles publiquement.

info

Pour les fonctionnalités nécessitant un identifiant utilisateur (comme le suivi de progression), un deviceId unique est utilisé. Ce deviceId peut être généré côté client et stocké localement.

Format des données​

L'API utilise JSON pour toutes les requêtes et réponses. Les en-têtes HTTP suivants sont utilisés :

  • Content-Type: application/json pour les requêtes POST
  • Accept: application/json pour toutes les requêtes

Versioning​

Actuellement, l'API est en version 1.0. La version future sera indiquée dans l'URL de base si nécessaire.

Rate Limiting​

attention

Des limites de taux peuvent être appliquées pour éviter les abus. En cas de dépassement, vous recevrez une réponse HTTP 429 (Too Many Requests).

Les limites exactes seront communiquées dans les en-têtes de réponse :

  • X-RateLimit-Limit : Nombre maximum de requêtes autorisées
  • X-RateLimit-Remaining : Nombre de requêtes restantes
  • X-RateLimit-Reset : Timestamp de réinitialisation

Codes de statut HTTP​

L'API utilise les codes de statut HTTP standards :

  • 200 OK : Requête réussie
  • 201 Created : Ressource créée avec succès
  • 400 Bad Request : Requête invalide
  • 404 Not Found : Ressource non trouvée
  • 429 Too Many Requests : Trop de requêtes
  • 500 Internal Server Error : Erreur serveur

Gestion des erreurs​

En cas d'erreur, l'API retourne un objet JSON avec les informations suivantes :

{
  "statusCode": 404,
  "message": "Ville avec l'ID abc123 non trouvée",
  "error": "Not Found"
}

Exemples de requêtes​

JavaScript (fetch)​

const response = await fetch('https://api.wast-o.com/public/cities');
const { data: cities } = await response.json();
console.log(cities);

TypeScript (avec types)​

interface City {
  id: string;
  name: string;
  country: string;
  // ...
}

const response = await fetch('https://api.wast-o.com/public/cities');
const { data: cities } = await response.json();

cURL​

curl https://api.wast-o.com/public/cities

Prochaines étapes​