/Vérifié le 13 novembre 2026

API de serrures : comment leurs versions s'empilent et pourquoi vous devez tout gérer en même temps

Pourquoi l'API d'un fabricant de serrures change-t-elle, et pourquoi ses anciennes versions restent-elles à la charge de celui qui intègre ?

L'API d'un fabricant de serrures peut être amenée à changer pour au moins trois raisons, sans que ses anciennes versions ne disparaissent quand la nouvelle version est publiée. Elle peut changer parce que certains appareils apportent des capacités qu'elle ne savait pas décrire, parce que des règles de sécurité ont été durcies, et enfin parce que les règles commerciales ou la plateforme ont changé. À chaque fois, l'ancienne version de l'API reste en service chez une partie des clients, si bien que pour continuer de faire fonctionner ce que vous aviez fait fonctionner, vous vous retrouvez à devoir prendre en charge toutes les versions en même temps.

Ce que vous lisez ici est une facette parmi d'autres de ce que nous appelons, chez Seam, « l'enfer des intégrations directes avec les API des fabricants », et que nous gérons à la place de nos clients. Cette section comprend quelques articles qui présentent d'autres exemples.

L'API change lorsque les fonctionnalités ou la typologie des objets évoluent

Nuki publie plusieurs API pour une même serrure. L'une tourne dans le cloud de Nuki, et un logiciel l'appelle pour piloter des serrures à distance, depuis n'importe où. Une autre tourne dans le petit boîtier, appelé , qui relie la serrure au Wi-Fi de la maison, et elle ne répond qu'aux appels venus du même réseau local.

Le document qui décrit l'API locale du bridge de Nuki contient un historique de quatorze versions, égrené de la 1.6 en juin 2017 à la 1.13.3 en octobre 2024 (Nuki, Bridge API 1.13.3, PDF).

L'apparition d'un nouveau modèle de serrure n'y change en général rien : une serrure qui se comporte comme la précédente s'adresse à la même API, à l'octet près, comme la Smart Lock 2.0 après la 1.0. Ce qui amène à modifier l'API, c'est l'apparition d'un appareil qui fait quelque chose que l'API ne savait pas encore décrire. Cinq des quatorze versions sont de ce type :

  • En mai 2019, la 1.9 introduit des « types d'appareil », parce que l'Opener, un module d'interphone, n'est pas une serrure. Les appels qui visent un appareil sont alors amenés à inclure un nouveau paramètre deviceType.
  • En juillet 2020, la 1.11 ajoute les états du capteur de porte.
  • En septembre 2020, la 1.12 ajoute l'état de la pile du clavier.
  • En novembre 2021, la 1.13.0 ajoute la Smart Door à la liste des types. La Smart Lock 3.0, sortie au même moment, n'y obtient qu'une valeur de plus dans cette liste.
  • En décembre 2021, la 1.13.1 ajoute les états d'un capteur de porte externe.

Deux autres versions ont pour objet de renforcer la sécurité. Les sept restantes ne touchent qu'à la documentation, à des corrections ou à des commodités d'appel.

Même une commodité d'appel peut dépendre du matériel. En janvier 2020, la version 1.10 a ajouté des « actions simples », un appel /lock et un appel /unlock, qui ne marchent que si le boîtier et la serrure ont chacun un firmware assez récent. L'API donne les deux versions, mais le boîtier ne relève celle de la serrure qu'une fois par jour (Nuki, forum des développeurs) : le logiciel qui l'appelle a donc deux versions à vérifier, dont l'une peut-être périmée, avant de savoir si l'appel marchera.

Dans la mesure du possible, le fabricant s'efforcera de faire en sorte qu'aucun de ces ajouts n'amène à casser les logiciels existants, car rien ne peut obliger directement les logiciels qui se servent déjà de l'API à se mettre à jour. Le paramètre deviceType qui a été introduit en 2019, par exemple, « vaut 0 par défaut », ce qui correspond au seul type d'appareil initial, les serrures. En procédant ainsi, Nuki s'assure qu'un appel écrit avant 2019 (et qui ne passait donc pas ce paramètre) continuera de fonctionner. Les applications d'avant 2019 peuvent ainsi continuer de verrouiller et déverrouiller sans erreur les serrures qui existaient alors. En revanche, elles ne connaîtront ni les types d'appareil ni les états de capteur ajoutés depuis, et elles ne sauront pas les traiter quand les boîtiers les leur transmettront.

L'API cloud de Nuki, celle que les logiciels appellent à distance, a changé de la même manière, par ajout. Elle envoie des webhooks, c'est-à-dire des messages que le cloud de Nuki adresse au logiciel quand une serrure change d'état. Leur version 1.0 sort en décembre 2020, après plusieurs bêtas fermées. La première bêta, bâtie sur d'autres adresses d'appel, « reste disponible pour l'instant », avec la demande de migrer parce qu'elle « sera très probablement dépréciée dans le courant de l'année 2021 » (Nuki, Web API webhooks). Deux façons de recevoir ces messages sont donc en service en même temps, jusqu'à ce que tous les logiciels aient migré, et un logiciel branché sur cette API doit savoir lire les deux.

La sécurité se durcit avec des montées de versions, sans invalider les versions d'avant

Nuki vend, à côté de ses serrures, un petit boîtier appelé bridge, qui se branche sur une prise et relie la serrure au Wi-Fi de la maison. Ce boîtier répond à des appels venus du réseau local de la maison. Ces appels forment l'API locale de Nuki, que Nuki décrit dans un document public, le Bridge API. Pour déverrouiller la porte, un logiciel appelle une adresse du boîtier, comme on ouvre une page web : http://192.168.1.50:8080/lockAction?nukiId=1&deviceType=0&action=1&token=123456. Le dernier élément de l'adresse, le jeton, est un mot de passe. Le boîtier n'exécute l'ordre que si ce jeton est celui qu'il connaît.

Envoyer un mot de passe dans une adresse, en HTTP, pose un problème connu. N'importe quel appareil capable de capter le trafic de ce réseau peut lire la requête, et quiconque l'a lue peut la renvoyer telle quelle pour ouvrir la porte à son tour. Nuki a donc fait évoluer la façon de s'authentifier, en deux étapes.

La première étape est le jeton haché. Au lieu du mot de passe, le logiciel envoie l'heure, un nombre tiré au hasard et une empreinte, c'est-à-dire le résultat d'un calcul fait à partir de ces deux valeurs et du mot de passe, qu'on ne peut pas remonter à l'envers. Le boîtier refait le calcul de son côté et compare. Une requête capturée ne sert plus à rien, parce que le boîtier refuse une empreinte trop ancienne ou déjà reçue. La deuxième étape est le jeton chiffré, qui ne laisse plus rien lire du jeton en clair dans l'adresse et ne vaut que soixante secondes.

Le jeton haché arrive dans la version 1.8 de ce document, en mars 2019, « comme alternative plus sûre à l'envoi du jeton en clair » (Nuki, Bridge API 1.13.3, PDF). Le jeton chiffré arrive dans la version 1.13.2, en juin 2022. Dans la version 1.13.3, d'octobre 2024, le jeton haché est marqué « déprécié ». Et le jeton en clair, le mot de passe écrit dans l'adresse, est toujours accepté : le document le réserve « aux tests et aux Wi-Fi ou VLAN privés et sécurisés », mais il fonctionne.

En sept ans, le fabricant a donc ajouté deux façons de s'authentifier et n'en a retiré aucune. Retirer l'une de ces façons de s'authentifier casserait, le jour même, tous les logiciels tiers qui l'emploient encore, et ces logiciels ne sont pas les siens. Le logiciel qui intègre ce type d'API doit donc conserver ces trois façons de s'authentifier dans son code, et rien n'indique à quelle date il deviendra possible d'en abandonner une.

Le fabricant change ses règles et fixe une date

Les nouvelles versions d'API ajoutent le plus souvent des possibilités sans invalider les anciennes, afin que les logiciels écrits avant leur parution continuent de fonctionner.

Il arrive cependant qu'un fabricant puisse aussi décider de retirer une fonction, de changer les règles d'un appel, ou de soumettre cet appel à une condition nouvelle. Dans ce cas, les logiciels écrits avant le changement cessent de fonctionner. Dans le métier, on appelle cela un breaking change, c'est-à-dire un changement qui « casse » les logiciels existants, et le fabricant l'annonce le plus souvent avec une date. Quatre exemples publics illustrent quatre manières de le faire.

Le premier exemple vient de Salto, qui conçoit des serrures pour les bureaux et les immeubles et publie une API cloud pour sa plateforme KS. En février 2019, Salto a publié la version 1.1.10.6 de cette plateforme, une simple version de maintenance, et sa note de version indiquait que la mise à jour introduisait « un breaking change pour les points d'entrée GET entries et GET incidents ». Ces deux appels renvoyaient le journal des entrées et la liste des incidents d'un site. La même note précisait alors que le nouveau comportement n'était « pas encore pris en charge par tous les sites déployés » et que, pour l'heure, les données n'étaient renvoyées que pour les sites de test marqués « early birds » (Salto, Connect API release v1.1.10.6). Un même appel ne se comportait donc pas de la même façon sur tous les sites, et un logiciel qui lisait ce journal sur plusieurs sites devait savoir traiter les deux cas. On vous laisse imaginer les acrobaties que ce type de maintenance peut exiger quand on intègre des centaines d'API différentes.

Le deuxième exemple vient de l'API cloud de Nuki. Cette API sert, entre autres, aux logiciels de location de courte durée, qui créent et suppriment des codes d'accès pour les voyageurs. En juin 2023, Nuki a publié la version 1.5.0 de cette API avec un avertissement. À partir du 1er septembre 2023, affirmait-elle, les appels concernés « renverront un message d'erreur si la Smart Lock ou la Smart Door ne dispose pas d'un abonnement Smart Hosting actif », c'est-à-dire de l'abonnement que Nuki propose aux loueurs. La version 1.4.0 a été dépréciée le 31 août, et la note ajoutait que « cela pourrait entraîner le dysfonctionnement complet de l'application » (Nuki, Web API v1.5.0). Les serrures n'avaient pas changé, pas plus que la forme des appels d'API. Seule une condition d'abonnement était venue s'ajouter, et voilà qu'un logiciel qui fonctionnait la veille se retrouvait piégé le lendemain, alors que les serrures fonctionnaient toujours.

Le troisième exemple est celui d'un changement de plateforme. En 2023, hors des États-Unis et du Canada, Yale a remplacé son application Yale Access par une nouvelle application, Yale Home, et a annoncé que « les services de l'application Yale Access cesseraient de fonctionner à partir du 1er juillet 2023 » (Yale, Introducing the new Yale Home App). Les liaisons avec d'autres services, comme Airbnb, Google Home ou SmartThings, ne furent pas transférées et durent être rétablies sur la nouvelle plateforme. Une page de support en a tenu le registre, intégration par intégration et région par région, avec la mention « disponible » ou « bientôt disponible » (Yale, Yale Access to Yale Home integrations). Les logiciels branchés sur l'ancienne plateforme n'avaient donc pas seulement à prendre en charge une nouvelle version : chacune de leurs liaisons avec un produit Yale devait être rétablie, avec une date limite.

Le quatrième exemple vient d'une plateforme, et non d'un fabricant de serrures. SmartThings, la plateforme domotique de Samsung, pilote depuis une même application des appareils de nombreuses marques. Pour parler à chacun, elle utilise un petit programme appelé pilote, qui traduit ses ordres dans le langage de l'appareil. Pendant des années, ces pilotes ont été écrits dans un langage de programmation appelé Groovy.

En août 2022, SmartThings a annoncé qu'il abandonnait Groovy. Les anciens pilotes seraient remplacés par ceux d'un nouveau système, appelé Edge, à partir du 30 septembre, et les outils qui servaient à les écrire perdraient certaines de leurs fonctions le 15 octobre. La même annonce prévenait que les appareils « qui ne sont plus pris en charge depuis un certain temps par leurs fabricants sur l'ancienne plateforme » « ne seront pas migrés » (SmartThings, The End of Groovy Has Arrived).

Les serrures pilotées via SmartThings ont donc changé de pilote sans que leurs fabricants n'aient rien fait. Les serrures dont les fabricants n'assuraient plus la maintenance n'ont pas été migrées du tout. Voilà pourquoi un logiciel qui passe par une plateforme se doit d'assurer la maintenance des versions de cette plateforme, en plus de celles de chaque fabricant.

Chaque événement sédimente une couche logique dans le code de l'intégrateur, aucun n'en supprime

Chacun de ces événements qui impliquent l'apparition d'une nouvelle version d'API requiert du logiciel qui s'intègre avec ces API d'intégrer une couche logique supplémentaire pour aiguiller les différentes possibilités.

Même en intégrant l'API d'un seul fabricant, il peut falloir incorporer toute une logique conditionnelle pour savoir traiter les cas de nouveaux types d'appareils ou d'états qui n'existaient pas à l'origine, relayer différentes méthodes d'authentification et sélectionner la bonne selon le boîtier, vérifier que le boîtier et la serrure sont chacun assez récents pour la fonction appelée, etc. On peut avoir à traiter une erreur d'abonnement apparue à une date donnée, tout en préservant le comportement antérieur pour les serrures qui n'y sont pas soumises, voire refaire entièrement une intégration quand une plateforme en remplace une autre.

Toutes ces couches logiques s'additionnent, parce qu'à chaque fois, le service que vous rendez via votre logiciel implique d'autres parties prenantes, des sites physiques ou des logiciels qui continuent d'utiliser les anciennes versions.

Ensuite, il faut recommencer pour la marque suivante, chacune ayant ses propres péripéties et bien souvent les mêmes contraintes (nouveaux appareils, sécurité, mise en conformité, dépendances tierces, etc.).

Chaque changement ajoute une couche, aucun n’en supprimeQuelques versions des API du boîtier et du cloud de Nuki, de 2017 à 2024. Chaque bande est une logique que l’intégrateur doit encore garder.
Une pile de bandes qui monte de juin 2017 en bas à juin 2023 en haut, une par changement retenu dans les API de Nuki, à côté d'une photo du Nuki Bridge. En bas, la Bridge API 1.6, le jeton en clair dans l'adresse, toujours accepté. Puis la 1.8, le jeton haché, déprécié mais accepté ; la 1.9, les types d'appareil pour l'Opener ; la 1.10, les actions simples, si le firmware suit ; la 1.11, les états du capteur de porte ; la 1.12, la pile du clavier ; les webhooks 1.0 de l'API cloud, avec la première bêta maintenue ; la 1.13.0, le type Smart Door ; la 1.13.1, un capteur de porte externe ; la 1.13.2, le jeton chiffré ; et l'API cloud 1.5.0 de juin 2023, avec un abonnement exigé dès le 1er septembre. Les couleurs donnent la raison : le catalogue grandit, la sécurité se durcit, les règles changent à une date, ou un autre ajout. Une note en haut : la Bridge API 1.13.3, d'octobre 2024, marque le jeton haché comme déprécié, et rien n'est retiré de la Bridge API.
Chaque changement ajoute une couche, aucun n’en supprimeQuelques versions des API du boîtier et du cloud de Nuki, de 2017 à 2024. Chaque bande est une logique que l’intégrateur doit encore garder.
Une pile de bandes qui monte de juin 2017 en bas à juin 2023 en haut, une par changement retenu dans les API de Nuki, à côté d'une photo du Nuki Bridge. En bas, la Bridge API 1.6, le jeton en clair dans l'adresse, toujours accepté. Puis la 1.8, le jeton haché, déprécié mais accepté ; la 1.9, les types d'appareil pour l'Opener ; la 1.10, les actions simples, si le firmware suit ; la 1.11, les états du capteur de porte ; la 1.12, la pile du clavier ; les webhooks 1.0 de l'API cloud, avec la première bêta maintenue ; la 1.13.0, le type Smart Door ; la 1.13.1, un capteur de porte externe ; la 1.13.2, le jeton chiffré ; et l'API cloud 1.5.0 de juin 2023, avec un abonnement exigé dès le 1er septembre. Les couleurs donnent la raison : le catalogue grandit, la sécurité se durcit, les règles changent à une date, ou un autre ajout. Une note en haut : la Bridge API 1.13.3, d'octobre 2024, marque le jeton haché comme déprécié, et rien n'est retiré de la Bridge API.
Dix des quatorze versions de la Bridge API figurent ici, note comprise, avec deux changements de l'API cloud. Les quatre absentes ne touchent qu'à la documentation, à des corrections ou à des commodités d'appel.
Trois raisons de versionner, et ce que chacune laisse à porter
Qui décideCe que l'intégrateur voitCe qu'il doit garder
Le catalogue granditLe fabricant, à chaque produitDes types et des états inconnus de son codeLa tolérance aux valeurs qu'il ne connaît pas encore
La sécurité se durcitLe fabricant, sans retirer l'ancienne façon de s'authentifierPlusieurs façons de s'authentifier acceptées pour un même appelToutes ces façons, et le choix de la bonne selon le boîtier
Les règles changentLe fabricant, avec une dateUn breaking change annoncé, une erreur nouvelle, une migrationL'ancien comportement jusqu'à la date, le nouveau après

Les deux premiers exemples sont des cas d'ajout de fonctionnalités, le troisième correspond au retrait d'une fonction à une date annoncée. Pourtant aucune de ces raisons ne dispense le logiciel de continuer d'assurer la prise en charge des versions précédentes.

Ce que nous venons de décrire, c'est le travail que Seam fait à la place de ses clients. Nous suivons ces versions fabricant par fabricant et nous les portons toutes derrière une seule API. Le logiciel qui commande une serrure à travers nous n'a donc ni à connaître les versions du boîtier et de la serrure d'en face, ni à garder trois façons de s'authentifier. Dans un autre article, nous expliquons ce que cette couche ajoute au-dessus des API de fabricants.

Smart Locks
Access Systems
Lock Capabilities
Thermostats
Sensors
© 2026 Seam Labs, Inc.