API des codecs

L’API des codecs sert la bibliothèque de codecs et vos propres codecs aux personnes, aux scripts et aux routeurs sous licence. Utilisez-la pour conserver les codecs dans le contrôle de version, les publier depuis un pipeline ou tester des payloads depuis vos propres outils.

Les chemins ci-dessous suivent la forme habituelle https://<votre hôte>/tenant/<tenantId>/api/…. Envoyez une clé d’API sous la forme Authorization: Bearer <clé d'API>. Voir Principes de base de l’API REST.

Routes

Méthode et chemin	Permission	Réponse
GET /api/iot/lorawan/codecs	Facultative (voir ci-dessous)	L’index des codecs : { version, scope, codecs: [...], sig: null }
GET /api/iot/lorawan/codecs/<codecId>	Facultative	Un codec : { id, rev, sha256, scope, document, outputSet }
GET /api/iot/lorawan/codecs/bundle	Facultative	Tous les codecs avec leur document, compressés : { version, codecs: [{ id, rev, sha256, scope, document }] }
GET /api/iot/lorawan/codec-library	Consulter les codecs	La liste affichée dans le tiroir des codecs (paginée, triable, deux sources)
POST /api/iot/lorawan/codecs	Gérer les codecs	Publier un nouveau codec (201)
PATCH /api/iot/lorawan/codecs/<codecId>	Gérer les codecs	Publier une nouvelle révision de votre codec
DELETE /api/iot/lorawan/codecs/<codecId>	Gérer les codecs	Supprimer votre codec
POST /api/iot/lorawan/codecs/<codecId>/test	Consulter les codecs	Décoder une trame avec un codec enregistré
POST /api/iot/lorawan/codecs/test	Consulter les codecs	Vérifier un document de codec et décoder éventuellement une trame ; rien n’est enregistré
GET /api/iot/lorawan/codecs/<codecId>/revisions	Consulter les codecs	Les révisions du codec

« Consulter les codecs » est la permission de consulter les codecs LoRaWAN et d’utiliser le banc d’essai (utilisateurs par défaut). « Gérer les codecs » est la permission d’ajouter, de modifier et de supprimer vos propres codecs (administrateurs par défaut).

Qui voit quoi sur les trois routes de lecture

Identifiant envoyé	Réponse
Aucun	La bibliothèque publique uniquement. Mise en cache pendant 5 minutes (Cache-Control: public, max-age=300).
Une session valide ou une clé d’API avec la permission de consultation	La bibliothèque et les codecs de votre organisation. Non mis en cache (private, no-store).
La requête signée d’un routeur sous licence	La bibliothèque et les codecs de l’organisation du routeur.
Un identifiant présent mais incorrect (en-tête erroné, session expirée, clé inconnue)	401 avec invalid_credentials, signature_expired ou certificate_revoked. Jamais la liste publique.
Un identifiant valide sans la permission requise	403

Filtres et mise en cache

L’index accepte q (recherche), vendor, model, oui, fport et scope. Chaque réponse porte un ETag égal à la version de l’index ; renvoyez-le dans If-None-Match pour obtenir 304 Not Modified si rien n’a changé.

GET …/codecs/<codecId>?sha256=<empreinte> demande une révision exacte. Un codec retiré répond 410 (codec_withdrawn).

Publier un codec

POST /tenant/<tenantId>/api/iot/lorawan/codecs
Content-Type: application/json

{ "document": { "id": "t.room-sensor", "title": "…", "vendor": "…", "kind": "layout", "frames": [ … ], "tests": [ … ] } }

Ou copier un codec de la bibliothèque :

{ "copyOf": "<library codec id>", "id": "t.my-copy" }

La réponse est 201 { codec, indexVersion }. Les codecs de la bibliothèque ne peuvent pas être modifiés ou supprimés par ces routes : 403 codec_read_only.

Tester une trame

POST /tenant/<tenantId>/api/iot/lorawan/codecs/t.room-sensor/test
Content-Type: application/json

{ "fport": 2, "hex": "0BC4010A32" }

fport va de 1 à 255 et hex compte au plus 255 octets. Une trame invalide répond Saisissez le FPort (1-255) et le payload en chiffres hexadécimaux (255 octets au maximum).

Limites de débit

Appelant	Limite
Sans identifiant : index et codec unique	60 requêtes par minute et par adresse
Sans identifiant : bundle	6 par heure et par adresse
Utilisateurs connectés et clés d’API	240 par minute ; bundle 30 par heure
Routeurs sous licence	120 par minute et par certificat d’appareil

Au-delà d’une limite, l’API répond 429 (Trop de requêtes. Réessayez plus tard.).

Codes d’erreur

Statut	details.reason	Signification
404	—	Codec introuvable.
409	codec_exists	Un codec portant cet identifiant existe déjà. Choisissez un autre identifiant.
410	codec_withdrawn	Cette révision du codec a été retirée.
403	codec_read_only	Les codecs de la bibliothèque ne se modifient pas ici : enregistrez une copie et modifiez la copie.
422	codec_format_not_supported	Un décodeur JavaScript a été envoyé.
422	codec_tests_failed	Les vecteurs de test ont échoué ; les vecteurs en échec sont listés.
422	codec_incompatible	La nouvelle révision supprime des clés ou modifie des unités.
422	codec_model_claimed	Un autre de vos codecs couvre ce modèle.
422	codec_choice_unknown	(Lorsqu’un appareil ou un profil choisit un codec) le codec n’existe pas ou a été retiré.
401	invalid_credentials	Les identifiants envoyés avec cette requête ne sont pas valides.

Pour l’API LoRaWAN complète (passerelles, appareils, clés, appairage, trames), voir l’API LoRaWAN.