Référence API

01Authentification

Toutes les requêtes à l'API doivent être authentifiées à l'aide d'une clé API. La clé est transmise via l'en-tête HTTP X-API-KEY ou API-KEY (les deux formes sont acceptées, mais ne peuvent pas être utilisées simultanément). Vous pouvez générer vos clés depuis la page Mes ressources.

X-API-KEY: votre-clé-api

GETRécupérer des données

Utilisez la méthode GET pour récupérer une ressource identifiée par son chemin. Le chemin suit une structure /ressource/identifiant librement définie.

Récupérer une ressource

GET https://api.simpleapi.fr/user
Accept: application/json
X-API-KEY: votre-clé-api

Récupérer une ressource par identifiant

GET https://api.simpleapi.fr/user/1234
Accept: application/json
X-API-KEY: votre-clé-api

Exemple de réponse

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "active": true
}

POSTCréer ou mettre à jour des données

La méthode POST crée ou met à jour (upsert) une ressource à un chemin donné. Si la ressource existe déjà, elle est remplacée intégralement.

Créer une ressource

POST https://api.simpleapi.fr/user/1234
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "active": true
}

Mettre à jour une ressource existante

POST https://api.simpleapi.fr/user/1234
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "name": "John Doe Updated",
  "email": "john.updated@example.com",
  "age": 31
}

PUTMettre à jour des données

La méthode PUT fonctionne de manière identique à POST et peut être utilisée comme alternative pour mettre à jour une ressource.

PUT https://api.simpleapi.fr/user/1234
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "age": 28,
  "role": "admin"
}

DELETESupprimer des données

La méthode DELETE supprime définitivement une ressource à l'identifiant spécifié.

DELETE https://api.simpleapi.fr/user/1234
X-API-KEY: votre-clé-api

GETCollections et pagination

Lorsque le chemin se termine par un segment sans identifiant, l'API retourne une collection paginée par curseur. Passez cursor= (vide) pour démarrer depuis le début, puis utilisez la valeur nextCursor retournée pour la page suivante.

Première page (taille configurée)

GET https://api.simpleapi.fr/user
Accept: application/json
X-API-KEY: votre-clé-api

Pagination par curseur (20 éléments)

GET https://api.simpleapi.fr/user?cursor=&pageSize=20
Accept: application/json
X-API-KEY: votre-clé-api

Paramètres de pagination

Exemple de réponse

{
  "data": [
    { "name": "John Doe", "email": "john@example.com" },
    { "name": "Jane Doe", "email": "jane@example.com" }
  ],
  "meta": {
    "pageSize": 20,
    "nextCursor": "dXNlcl8x",
    "hasNextPage": true
  }
}

POSTFichiers binaires & images

La méthode POST n'est pas limitée au JSON. Vous pouvez stocker n'importe quel contenu binaire — image, PDF, fichier texte, etc. — en précisant le Content-Type correspondant dans l'en-tête de la requête. Le contenu original et son type MIME sont conservés tels quels, et renvoyés à l'identique lors d'un GET.

Stocker une image PNG

POST https://api.simpleapi.fr/photos/avatar
Content-Type: image/png
X-API-KEY: votre-clé-api

<données binaires de l'image>

Récupérer l'image

GET https://api.simpleapi.fr/photos/avatar
X-API-KEY: votre-clé-api

Content-Type: image/png

<données binaires de l'image>

Stocker un document PDF

POST https://api.simpleapi.fr/documents/rapport
Content-Type: application/pdf
X-API-KEY: votre-clé-api

<données binaires du PDF>

Limites de taille

La taille maximale d'un seul envoi est de 1 024 Ko. Un dépassement retourne une réponse 413 Payload Too Large.

GET / POST / PUTChemins imbriqués

L'API supporte des chemins arbitrairement profonds pour modéliser des hiérarchies de ressources. La structure est libre : vous définissez votre propre arborescence d'endpoints.

Récupérer une sous-ressource

GET https://api.simpleapi.fr/user/1234/command/4567
Accept: application/json
X-API-KEY: votre-clé-api

Créer une sous-ressource

POST https://api.simpleapi.fr/user/1234/command/4567
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "action": "delete",
  "resource": "document-123",
  "status": "pending"
}

Mettre à jour une sous-ressource

PUT https://api.simpleapi.fr/user/1234/command/4567
Content-Type: application/json
X-API-KEY: votre-clé-api

{
  "action": "execute",
  "status": "completed",
  "result": "success"
}

Exemple de chemin profond

GET https://api.simpleapi.fr/org/acme/team/dev/member?cursor=&pageSize=25
Accept: application/json
X-API-KEY: votre-clé-api

En-têtesMétadonnées

Des en-têtes HTTP supplémentaires permettent de contrôler le cycle de vie de vos ressources.

Expiration automatique (EXPIRESAT)

L'en-tête EXPIRESAT définit une date d'expiration pour la ressource au format ISO 8601. Une fois la date atteinte, la ressource est automatiquement supprimée.

POST https://api.simpleapi.fr/user/1234
Content-Type: application/json
X-API-KEY: votre-clé-api
EXPIRESAT: 2028-01-01T00:00:00Z

{
  "name": "John Doe",
  "email": "john@example.com"
}

En-têtes disponibles

LimiteNombre de ressources par espace

Chaque espace SimpleAPI peut accueillir jusqu'à 120 ressources distinctes par défaut. Une ressource correspond à un type d'objet identifié par le premier segment de votre chemin (/user, /product, /order, etc.).

Cette limite est liée au nombre de routes actives dans votre espace : chaque ressource génère ses propres routes GET, POST, PUT et DELETE. Pour garantir des performances optimales même sous forte charge, la plateforme applique un plafond technique sur ce nombre de routes. 120 ressources devraient largement suffire pour la très grande majorité des projets, y compris les applications complexes avec de nombreux types d'objets.

Comportement en cas de dépassement

Lorsque la limite est atteinte, toute tentative de création d'une nouvelle ressource retourne une réponse 429 Too Many Requests.

{
  "error": "Limite de ressources atteinte (max 120). Supprimez des ressources inutilisées ou contactez le support pour augmenter cette limite."
}

Ressources comptabilisées

4xx / 5xxGestion des erreurs

L'API retourne des codes HTTP standards et un corps JSON décrivant l'erreur rencontrée.

Codes d'erreur courants

Exemple d'erreur — Clé API manquante

GET https://api.simpleapi.fr/user/1234
Accept: application/json

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}