Documentation
Contact
Référence API

Migrer de la v3.1 vers la v3.2

La version 3.2 de l'API MLS CONNECT est servie sous le préfixe /api/v3.2/. Les préfixes /api/v3/ et /api/v3.1/ continuent de servir les versions 3.0 et 3.1, sans aucun changement. Vous migrez donc quand vous le décidez : rien ne change pour vous tant que vous n'avez pas modifié vos URLs.
La 3.2 ne change aucun champ : les réponses ont exactement la même forme qu'en 3.1. Elle corrige le code HTTP de trois cas d'erreur, qui étaient servis en 400 quelle qu'en soit la cause. La description complète de chaque route et de chaque champ est dans la documentation de référence, qui décrit la version 3.2.

Ce qui change

Cas 3.0 et 3.1 3.2
apiKey ou apiToken absent, invalide, ou accès à l'API désactivé 400 401
Donnée refusée par une validation à l'enregistrement 400 422
Erreur interne du serveur 400 500
Le corps de l'erreur garde sa forme, {"errors": "…"}, avec le même message pour les deux premiers cas.

Identifiants refusés : 401

Une requête sans apiKey ni apiToken, avec un couple inconnu, ou portée par un accès désactivé, répond 401.
// v3.1 — 400
// v3.2 — 401
{"errors": "Not Authorized"}
À faire : si vous détectez un problème d'identifiants en testant le code 400, testez 401.

Validation refusée : 422

Quand une donnée envoyée en création ou en mise à jour est refusée par une règle de validation, la réponse est 422. La plupart des routes d'écriture répondaient déjà ainsi ; les autres répondaient 400, et s'alignent en 3.2. Le message liste les champs refusés.
À faire : traiter 422 comme un refus de la donnée envoyée, à corriger avant de renvoyer la requête.

Erreur interne : 500

Une erreur imprévue côté serveur répond 500, sans le détail technique de l'erreur, qui pouvait contenir des éléments internes.
// v3.1 — 400
{"errors": "<message technique>"}

// v3.2 — 500
{"errors": "Internal Server Error"}
À faire : traiter 500 comme une panne temporaire, que vous pouvez retenter plus tard. Un 400 désigne désormais toujours une requête à corriger de votre côté : la renvoyer à l'identique donnera le même résultat.

Marche à suivre

  1. Relire votre gestion des erreurs sur les trois codes ci-dessus. Si vous ne distinguez pas les erreurs par leur code, rien ne change pour vous.
  2. Tester sur /api/v3.2/ avec vos clés habituelles. Les mêmes clés apiKey et apiToken servent tous les préfixes, sur les mêmes boards.
  3. Contrôler l'en-tête X-Api-Version de vos réponses : il vaut 3.2 sur le nouveau préfixe.
  4. Basculer le préfixe dans votre configuration. Aucune autre modification d'URL n'est nécessaire : les routes sont identiques.
# avant
GET https://app.mls-connect.com/fr/api/v3.1/properties/search?mls_board=xxx

# après
GET https://app.mls-connect.com/fr/api/v3.2/properties/search?mls_board=xxx
Si vous êtes encore sur /api/v3/, passez directement à la 3.2 : appliquez en une fois les changements de champs décrits dans Migrer de la v3 vers la v3.1 et les codes HTTP ci-dessus.

Ce qui ne change pas

  • Les champs des réponses, leur forme et leur contenu
  • Les routes, leurs paramètres et leurs filtres
  • L'authentification par apiKey et apiToken, et les droits par board
  • La pagination et les curseurs
  • Le format d'écriture des biens, agences, utilisateurs et passerelles
  • Les autres codes HTTP : 404 sur une ressource introuvable, 422 sur un refus de donnée déjà signalé ainsi, 429 sur un dépassement de débit