iScriba API

L'API iScriba est une autre façon d'accéder à vos données iScriba — elle permet à des outils tiers d'interagir facilement avec le service. Ce guide devrait vous fournir tout ce dont vous avez besoin pour mettre en œuvre un logiciel qui fonctionne avec iScriba.

L'API essaye autant que possible de suivre les conventions REST. Ainsi les méthodes permettant de retrouver des données nécessitent une requête de type GET. Les méthodes qui envoient des données nécessitent une requête de type POST. Les modifications des requêtes de type PUT, et les suppressions des requêtes de type DELETE. Si votre client HTTP n'est pas en mesure d'effectuer des requêtes de type PUT et DELETE, vous pouvez utiliser une requête de type POST en précisant un champ _method.

Les conditions d'utilisation du service couvrent l'utilisation acceptable du service et de l'API (merci de porter une attention particulière à la section 8 : conditions particulières pour les développeurs). Au-delà de l'aspect légal, nous vous demandons de développer vos programmes avec considération — les clients sont tenus de se conformer au protocole HTTP 1.1, de faire du "cache" autant que possible, de limiter la fréquence des requêtes, et d'inclure une entête User-Agent. Si vous rencontrez un bug avec le service ou l'API, merci de nous donner une chance de le corriger avant de le rendre publique. Si vous avez des questions ou des problèmes, n'hésitez pas à contacter le support.

Public visé

Ce guide est destiné aux développeurs Web qui ont accès à un compte iScriba pour lequel l'API est activée.

Ces développeurs doivent avoir des connaissances dans un langage de programmation tels que PHP, .NET, Python, Perl, Ruby, Javascript ou avoir une expérience dans l'utilisation de services Web.

Haut

Conventions de notation

Tout au long de cette documentation, vous trouverez l'ensemble des conventions de notation suivantes :

#{expression}
Doit être remplacé par la valeur de l'expression. Par exemple : /#{user_id} devrait être remplacé par /12345 (en supposant que user_id = 12345).
[/argument/#{valeur}]
Indique un argument facultatif dans l'URI.
...
Par soucis de concision, nous avons omis des parties répétitives de la réponse.
<!-- commentaire -->
Commentaire facultatif par souci de clarification. La réponse réelle ne contient pas de commentaire.
Haut

Formats des réponses

Le format par défaut des réponses est le XML. Cependant, vous pouvez obtenir les réponses dans un format différent :

  • en ajoutant l'argument /format/#{format}
  • en spécifiant une entête Accept: #{format}
  • en ajoutant une extension à la fin d'une URI .#{format}

Les formats disponibles sont les suivants :

  • xml
  • json
  • jsonp (permet de spécifier une fonction de "callback" en passant l'argument /callback/#{my_function})
  • serialize
  • php (données brutes qui peuvent être utilisés avec eval())
Haut

Type d'erreurs

400 - Bad Request
La requête n'est pas formatée correctement ou des paramètres sont manquants. Vérifiez que vous n'avez pas oublié un paramètre requis.
401 - Access Denied
Vous n'êtes pas authentifié. Vérifiez que le jeton d'authentification est correct.
403 - Forbidden
Vous avez dépassé le nombre de requêtes maximum, l'API n'est pas activée pour le compte ou vous avez dépassé la limite de votre abonnement.
404 - Not Found
La ressource demandée n'est pas disponible.
406 - Not Acceptable
Le format demandé n'est pas disponible.
500 - Server Error
Il y a un problème avec le serveur. Réessayez après quelques minutes et contactez le support si le problème persiste.
501 - Not Implemented
La ressource demandée n'existe pas.
502 - Bad Gateway
L'API n'est pas disponible ou est en cours de mise à jour.
503 - Service Unavailable
L'API n'est pas en mesure de répondre à votre demande pour des raisons de capacité. Réessayez plus tard.
Haut

Limitation des requêtes

Nous avons fixé des limites de requête par méthode, par utilisateur et par heure pour éviter une charge inutile sur nos serveurs. Lorsque cette limite est dépassée iScriba envoie un code de statut HTTP 403 Forbidden.

Nous vous conseillons vivement de rendre vos applications conformes à cette limitation.

Lorsque vous appellez une méthode, vous avez la possibilité de connaitre le statut de la limitation via les entêtes suivantes :

X-FeatureRateLimit-Limit: 100 <!-- la limite par heure pour la méthode -->
X-FeatureRateLimit-Remaining: 99 <!-- le nombre de requêtes restantes -->
X-FeatureRateLimit-Reset: 1277234708 <!-- la date où la limite va être réinitialiser (en secondes) -->
Haut