L'API Eventmaker est implémentée sous forme de JSON et XML vanilla via HTTP à l'aide des quatre verbes (GET/POST/PUT/DELETE). Chaque ressource, telle que Event, Guest ou Check-in, possède sa propre URL et est manipulée de manière isolée. En d'autres termes, nous avons essayé de faire en sorte que l'API suive les principes REST.
Vous pouvez explorer la partie affichage de l'API (tout ce qui est récupéré avec GET) à l'aide d'un navigateur classique. Firefox est particulièrement adapté à cette tâche, car il dispose d'un bon rendu XML simple. Vous pouvez également obtenir un affichage agréable de la version JSON de l'API en installant JSON View.
Tester l'API
Avec curl
Vous pouvez tester l'API à l'aide de l'outil en ligne de commande curl. Si vous devez mettre à jour (PUT) ou créer (POST) une ressource JSON, utilisez le modèle suivant :
curl -X PUT -H "Content-Type: application/json" -d "{json_resource}" {url}.json?auth_token=YOUR_API_TOKEN
curl -X POST -H "Content-Type: application/json" -d "{json_resource}" {url}.json?auth_token=YOUR_API_TOKENOù {json_resource} est la charge utile à envoyer à l'API pour créer/mettre à jour une ressource.
Avec un Rest Client
Si vous préférez tester l'API avec un outil plus visuel, vous pouvez utiliser REST Client, un débogueur open source pour les services web RESTful, comme l'API Eventmaker ! Une extension Firefox très pratique est disponible, et les extensions Chrome et Safari sont en cours de développement.
Une documentation Swagger est disponible ici : https://app.eventmaker.io/swagger
Authentification
Lorsque vous utilisez l'API, c'est toujours par l'intermédiaire d'un utilisateur existant dans Eventmaker. Il n'y a pas d'utilisateur API spécial. Ainsi, lorsque vous utilisez l'API en tant que « john@company.org », vous pouvez voir et travailler seulement sur ce que John est autorisé à faire. L'authentification se fait à l'aide d'un jeton d'authentification, que vous trouverez dans votre profil utilisateur (vous devez être connecté).
Il vous suffit ensuite d'ajouter l'auth_token en tant que paramètre de requête de l'URL. Par exemple, vous pouvez récupérer un tableau JSON de tous les événements que vous gérez en envoyant la requête suivante :
GET /api/v1/events.json?auth_token=YOUR_API_TOKEN
Format
L'API Eventmaker prend en charge les formats XML et JSON. Vous pouvez choisir le format que vous préférez en ajoutant simplement .xml ou .json à la fin de l'URL de la ressource que vous interrogez.
Request
GET /api/v1/events.json?auth_token=YOUR_API_TOKEN
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
et pour la version XML :
Request
GET /api/v1/events.xml?auth_token=YOUR_API_TOKEN
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Dans la documentation des points de terminaison, nous utiliserons .format pour faire référence à .xml ou .json.
Lorsque vous souhaitez écrire des données dans l'API avec POST (création) ou PUT (mise à jour), vous devez spécifier un en-tête de requête de type de contenu.
Request
POST /api/v1/events/{event_id}/guests.json?auth_token=YOUR_API_TOKEN
Content-Type: application/json; charset=utf-8
Response
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
pour la version XML:
Request
POST /api/v1/events/{event_id}/guests.html?auth_token=YOUR_API_TOKEN
Content-Type: text/html; charset=utf-8
Response
HTTP/1.1 201 Created
Content-Type: text/html; charset=utf-8
Codes de retour API
L'API utilise les codes d'état HTTP suivants dans la réponse. Soyez attentif à ces codes, car ils vous indiquent si une erreur s'est produite.
200 OK - Pour toute méthode GET réussie.
201 Créé - Pour toute méthode POST réussie.
204 Aucun contenu - Pour toute méthode PUT ou DELETE réussie.
400 Bad Request - Vérifiez le corps de votre requête.
403 Forbidden - Vous avez peut-être oublié l'auth_token.
404 Not Found - La ressource n'existe pas.
406 Not Acceptable - Vous avez peut-être oublié le .format ou le Content-Type de la requête.
422 Unprocessable Entity - Vérifiez le corps de votre requête, le JSON ou le XML est peut-être mal formé.
Messages d'erreur
Si vous ne recevez pas de code d'état HTTP 2xx dans la réponse, cela signifie qu'une erreur s'est produite. Vous pouvez consulter le corps de la réponse pour obtenir plus d'informations sur les raisons pour lesquelles votre appel API n'a pas abouti.
JSON
En cas d'erreur générale, nous vous enverrons le message suivant :
DELETE /api/v1/events.json
// 404 Not Found
{
"error": "No API endpoint found at /api/v1/events and method DELETE"
}
Désormais, en cas d'erreur dans la charge utile fournie pour créer (POST) ou mettre à jour (PUT) une ressource, nous détaillerons les erreurs de validation comme suit :
POST /api/v1/events/{event_id}.json
Content-Type: application/json; charset=utf-8
{ "first_name": "Sébastien", "company_name": "Eventmaker" }// 422 Unprocessable Entity
{
"errors":
{
"uid":
[
"is invalid",
"can't be blank"
],
"guest_category_id":
[
"can't be blank"
],
"last_name":
[
"should be set, or at least one other element of identity: email, company or uid."
]
}
}
XML
Pour le même exemple ci-dessus, vous obtiendrez les réponses suivantes :
<!-- 404 Not Found -->
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>No API endpoint found at /api/v1/events and method DELETE</error>
</errors>
<!-- 422 Unprocessable Entity -->
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Guest Uid is invalid</error>
<error>Guest Uid can't be blank</error>
<error>Guest Category can't be blank</error>
<error>Last Name should be set, or at least one other element of identity: email, company or uid.</error>
</errors>