Encodage

Les données échangées à travers l’API HelloAsso, qu’elles soient passées en paramètres, ou retournées dans les réponses, respectent les normes suivantes :

  • chaine de caractères : l’encodage utilisé est l’UTF-8
  • dates : les dates sont représentées sous forme de timestamp au format ISO 8601. Le 1er février 2015 à midi est ainsi représenté par la chaine 20150201T120000
  • format du contenu de la réponse : JSON

Gestion des erreurs

Un code HTTP indique si l’appel a été correctement traité. Si ce code est différent de 200, cela signifie qu’un problème a été rencontré.

En particulier, voici les différents codes d’erreur HTTP qui sont susceptibles d’être retournés :

400 : Bad Request

L’url de l’appel est incorrect. Ce code correspond généralement à une valeur de paramètre incorrecte ou inexistante.

401 : Unauthorized

Les informations d’authentification sont incorrectes ou absentes.

404 : Not Found

L’appel a été correctement interprété et exécuté, mais la ressource demandée n’a pas été trouvée. En règle générale, cela indique que l’identifiant passé en paramètre est incorrect.

405 : Method Not Allowed

L’url de l’appel est correct, mais la méthode utilisée n’est pas supportée par cette ressource. Par exemple, un appel GET a été réalisé sur une ressource ne pouvant être accédée qu’avec la méthode POST.

426 : Update Required

L’appel a été correctement interprété, mais non exécuté. Ce code est retourné si l’appel est effectué dans un protocole non-sécurisé.

500 : Internal Server Error

Une erreur de traitement a été rencontrée par les serveurs HelloAsso. Dans ce cas, le problème doit être remonté à notre équipe afin que nous puissions en déterminer l’origine et, le cas échéant, appliquer un correctif.

503 : Service Unavailable

Ce code de retour indique que les serveurs HelloAsso sont surchargés. Dans ce cas de figure, l’appel doit être réitéré après le délai indiqué dans le champs d’en-tête Retry-After de la réponse.

Outre le code de réponse HTTP, les appels en erreur retournent une réponse contenant plus d’informations sur l’erreur rencontrée. Ces informations apparaissent sous deux formats. Le premier est un message à destination humaine, donnant une indication sur la possible origine du problème. Par exemple, si l’erreur provient d’un paramètre malformé, cela sera indiqué dans le message, avec le nom du paramètre en question.

Le deuxième format est un code d’erreur HelloAsso en notation reverse-domain, pouvant donc être automatiquement traité afin de mettre en place différents scénarios de réponses.

Voici les différents codes de réponses susceptibles d’être retournés :

com.helloasso.api.InvalidResource

La ressource demandée n’existe pas. La raison en est probablement une url malformée.

com.helloasso.api.MissingParameter

L’accès à la ressource nécessite un paramètre qui n’a pas été fourni. Le message indique alors le paramètre concerné.

com.helloasso.api.InvalidParameter

Un des paramètres fournis n’est pas au format attendu. Le message indique alors le paramètre concerné.

com.helloasso.api.InvalidIdentifier

Un paramètre d’identifiant a été fourni, ne correspondant à aucune donnée enregistrée sur l’application.

com.helloasso.api.NonSecureConnection

L’appel a été réalisé en HTTP, sur une ressource imposant le protocole HTTPS.

com.helloasso.api.ServiceUnavailable

La ressource est actuellement indisponible pour cause de maintenance. Le message indique alors la nature de la maintenance et le temps d’attente estimé avant que la ressource soit à nouveau disponible.

com.helloasso.api.ServerError

Une erreur s’est produite lors du traitement de la demande.

Format des chemins d'accès aux ressources

Le format canonique des urls d’accès aux ressources est le suivant :


<VERB> api.helloasso.com/<version>/<type>[/<id|slug>].<format>[?parameters]

[version] est l’identifiant de version de l’API utilisée. Celui-ci sera valorisé à v3. Les futures mises à jour importantes de l’API engendreront systématiquement un changement de numéro de version.

[type] est le type de ressource demandée. Celui-ci peut prendre différentes valeurs :

  • organizations
  • campaigns
  • actions
  • payments

[id] est l’identifiant unique de la ressource demandée. Celui-ci est normalement récupéré par un autre appel à l’API, ou fourni en retour d’un appel de création d’une nouvelle ressource.

[format] est le format de sérialisation souhaitée. Le format par défaut est le JSON, mais d’autres formats de sérialisation pourront être mis en place à l’avenir.

[parameters] est la chaine des paramètres optionnels attendu par la ressource demandée. Celle-ci se présente sous forme de query string d’url standard.

Format des réponses et pagination

Si l’appel à une resource est correcte, la réponse contient une representation JSON de la resource demandée. Les representations JSON des différentes ressources sont documentées dans le chapitre “Type de réponses”.

Certains appels retournent une collection de ressources. Dans ce cas, le format de la réponse est le suivant :


{
	"resources": [
	  {
	    // Representation JSON du type de resource demandée
	  }
	  …
	],
	"pagination": {
	  "page": "int",
	  "max_page": "int",
	  "result_per_page": "int"
	}
}

Élément Description
ressources Un tableau contenant les représentations JSON des ressources demandées
pagination.page La page courante de la collection retournée
pagination.max_page Le nombre de pages disponibles pour cette collection
pagination.result_per_page Le nombre de résultat par page

Retour