Conventions

Cette page décrit les conventions communes à la Public API et à la Devices API : l'enveloppe de réponse, les erreurs, la pagination, le filtrage, les dates et les identifiants. Lisez-la une fois avant d'écrire un client.

Enveloppe de réponse

Les deux API encapsulent chaque réponse JSON dans une enveloppe contenant un champ status, dans le style de JSend.

Succès :

{
  "status": "success",
  "data": { "id": 42, "name": "pump-01" }
}

Une opération qui ne renvoie aucun contenu répond 204 avec {"status": "success"}, ou sans corps.

Erreur :

{
  "status": "error",
  "message": "Resource not found"
}

Avec la CLI fun, ajoutez --data-only pour n'afficher que le champ data. Consultez La CLI fun.

Erreurs

Statut	Signification	Que faire
`400`	La requête est mal formée	Corrigez la requête
`401`	Les informations d'identification sont absentes, invalides ou expirées	Obtenez un nouveau jeton, par exemple avec `fun login`
`403`	Vous êtes authentifié, mais votre rôle n'autorise pas cette action, ou le type d'informations d'identification n'est pas le bon	Vérifiez votre rôle, consultez Rôles et autorisations
`404`	La ressource n'existe pas, ou ne se trouve pas dans ce projet	Vérifiez les identifiants
`409`	Conflit avec l'état actuel (Devices API)	Par exemple, l'appareil est déjà provisionné
`422`	Échec de la validation	Lisez `errors` et corrigez les champs listés
`429`	Trop de requêtes (Public API v2)	Attendez le nombre de secondes indiqué dans `Retry-After`, puis réessayez
`500`	Erreur du serveur	Réessayez plus tard. Contactez le support si le problème persiste

La Public API v2 ajoute un tableau errors aux échecs de validation :

{
  "status": "error",
  "message": "<summary>",
  "errors": [
    { "message": "<what is wrong>", "location": "body.name", "value": "<the value you sent>" }
  ]
}

La Devices API signale les problèmes 400 dans data.errors, chacun avec type, msg, path et location, et les problèmes 422 sous la forme d'un objet indexé par nom de champ. Consultez Devices API v3.

Limites de débit et quotas

Limite de débit. La Public API v2 limite le débit des requêtes par utilisateur. Au-delà de la limite, elle renvoie 429 avec un en-tête Retry-After. Patientez puis réessayez ; ne réessayez pas immédiatement en boucle.
Quotas de provisionnement. Chaque registre peut plafonner le nombre d'appareils de chaque type d'appareil qui peuvent y être provisionnés, et limiter le provisionnement à une fenêtre de temps (provisioning_start_at, provisioning_end_at). Définissez-les avec les opérations registries de la v2. Consultez Public API.

Pagination

Les opérations de liste sont paginées à l'aide de paramètres de requête :

Paramètre	Description	Valeur par défaut
`page`	Numéro de page, à partir de un	`1`
`item_per_page`	Éléments par page	`25`

La Public API v2 renvoie un objet pager à côté de data :

{
  "status": "success",
  "data": [],
  "pager": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "total": 120,
    "last_page": 5,
    "per_page": 25,
    "first_page_url": "...",
    "last_page_url": "...",
    "next_page_url": "...",
    "prev_page_url": null
  }
}

La Public API v1 renvoie un objet pagination avec current_page, from, to, total, last_page et per_page.

Filtrage, tri et relations

De nombreuses opérations de liste acceptent également :

Paramètre	Description	Exemple
`wheres`	Filtres, qui doivent tous correspondre. Expressions `field:operator:value` séparées par des virgules	`name:=:pump-01`
`or_wheres`	Filtres, dont l'un au moins peut correspondre	`name:=:pump-01,name:=:pump-02`
`order_by`	Trier selon un champ et une direction	`created_at:desc`
`with`	Ressources associées à inclure, séparées par des virgules	`roles`
`with_trashed`	Inclure les enregistrements supprimés lorsque la valeur est `true`	`false`

Toutes les opérations ne prennent pas en charge tous les paramètres. Vérifiez l'opération dans la spécification OpenAPI, ou exécutez fun api <version> <group> <operation> --help.

Dates et heures

Les horodatages de la Public API sont des chaînes ISO 8601 / RFC 3339 en UTC, par exemple 2026-01-01T12:00:00Z.
Les charges utiles des appareils sur MQTT utilisent le temps Unix en secondes (timestamp dans les états).
Les clés de provisionnement acceptent des dates au format YYYY-MM-DD, interprétées comme minuit UTC.
Les durées sont exprimées dans l'unité du champ, indiquée dans la spécification (par exemple, les délais d'expiration des fonctions sont en nanosecondes dans la spécification v2).

Identifiants

Identifiant	Format
ID d'organisation, de projet, de registre, d'appareil, de type d'appareil	Entiers
Numéro de série de l'appareil	Lettres minuscules, chiffres, `-` et `_`. Unique au sein d'un registre
ID de fonction	Chaîne opaque, par exemple `mvtvNUX9oWa9yFpdVLXYuR`
Clé de provisionnement	UUID

Les noms des paramètres de chemin suivent chaque version de l'API : la Public API v1 utilise le camelCase ({projectId}), la v2 et la Devices API utilisent le snake_case ({project_id}). La CLI fun convertit les deux en options en kebab-case (--project-id).

Les opérations qui font autre chose que créer, lire, mettre à jour ou supprimer utilisent un suffixe :verb, par exemple POST /v1/projects/{projectId}/actions/{actionId}:retry ou POST /v2/projects/{project_id}/functions/{function_id}:invoke.

Authentification

Chaque requête porte Authorization: Bearer <token>. Le jeton à utiliser dépend de l'API et du point de terminaison : consultez Authentification, Public API et Devices API v3.