Pourquoi une API plutôt qu'un flux XML
Un flux XML statique est lu en pull, à intervalle fixe, sans filtre ni contexte. Une API permet de demander précisément ce dont on a besoin : "tous les biens à vendre dans le 11ème arrondissement modifiés depuis hier". Cela divise par cent le volume de données échangées et permet le temps réel.
REST, GraphQL, RPC : choisir son style
Pour un écosystème immobilier français multi-clients, REST reste le meilleur compromis. C'est l'option choisie par Ts-Immo.
| Style | Force | Faiblesse | Quand l'utiliser |
|---|---|---|---|
| REST | Standard, cacheable, simple | Sur-fetching fréquent | API publique grand public |
| GraphQL | Requêtes précises, typé | Cache HTTP complexe | Apps mobiles, dashboards riches |
| gRPC / RPC | Très performant, binaire | Pas web-natif | Intégrations machine-to-machine |
Modèle de ressources immobilières
Une API immobilière sérieuse expose au minimum les ressources suivantes.
- /properties — les biens, avec leurs caractéristiques structurées.
- /properties/{id}/medias — les photos, plans, visites virtuelles.
- /agencies — les agences et leurs négociateurs.
- /contacts — la remontée de leads.
- /events — le flux d'événements pour webhook.
Authentification et sécurité
Trois schémas dominent : clé API en en-tête, OAuth2 client credentials pour les intégrations serveur-à-serveur, et OAuth2 authorization code pour les apps utilisateurs. Une API moderne combine clé API pour démarrer vite et OAuth2 pour les partenaires.
GET /v1/properties?city=Paris&status=available HTTP/1.1
Host: api.ts-immo.org
Authorization: Bearer ts_live_a1b2c3d4e5f6...
Accept: application/json
X-Request-Id: 7c4e9b2a-3f1d-4a8b-9e2c-5d6f7a8b9c0dPagination et tri
La pagination par offset ne tient pas à grande échelle : à la page 1000, la base relit 100 000 lignes pour en jeter 99 900. La pagination par curseur (cursor-based) résout ce problème en pointant directement sur la dernière ligne lue.
Recommandation Ts-Immo
Utilisez ?cursor=... plutôt que ?page=... pour parcourir un catalogue complet. Limitez page_size à 100 pour préserver les temps de réponse en deçà de 200 ms.
Filtrage et recherche
Une API immobilière doit accepter au minimum les filtres : ville, code postal, type de bien, transaction, prix min/max, surface min/max, nombre de pièces, et un filtre updated_since pour les synchronisations incrémentales.
Webhooks et événements
Les webhooks transforment l'API en architecture événementielle. Côté Ts-Immo, les CRM compatibles (Sweepbright, Whise) déclenchent property.created, property.updated, property.deleted, qui sont relayés aux sites web abonnés. Le receveur doit acquitter en moins de 5 secondes.
Rate limiting et quotas
Un rate limit protège l'API contre les abus et garantit l'équité entre clients. Ts-Immo applique 60 requêtes par minute en lecture standard, avec des en-têtes X-RateLimit-Remaining pour piloter le throttling côté intégrateur.
Versioning d'API
Le versioning par préfixe d'URL (/v1, /v2) reste le plus prévisible. Une API n'introduit jamais de breaking change dans une même version : ajout de champ oui, suppression ou renommage non.
Documentation et SDK
Une API mal documentée n'existe pas. La documentation doit être OpenAPI 3.1, avec exemples curl, JavaScript et PHP minimum. Un SDK officiel par langage majeur (JS, PHP, Python) divise par dix le temps d'intégration.
Observabilité
Côté fournisseur, chaque requête doit être tracée avec un X-Request-Id. Côté client, un dashboard expose les codes d'erreur, le taux de succès, et la latence. Ts-Immo offre cela nativement dans app.ts-immo.org.
Cas Ts-Immo
L'API Ts-Immo est exposée sur api.ts-immo.org, en REST, JSON, versionnée, documentée OpenAPI. Elle agrège 19 CRM dans un modèle unifié, sert les images via CDN, et émet des webhooks pour les CRM compatibles événementiel.