Pour utiliser l'API de Plum, vous devez dans un premier temps créer une application Plum. Pour cela vous devez avoir un compte Plum Premium et avoir accès au compte principal.

Allez dans espace "Compte" puis "Information" et enfin créer une application en spécifiant les caractéristiques d'une application Plum.

Vous obtiendrez une clé d'application qui vous sera demandé (comme le token d'utilisateur) lors de chaque requête à l'API de Plum.

En cas de piratage ou d'usurpation d'identité sur votre application, vous pouvez à tout moment regénérer la clé d'application. Attention : si votre clé est écrit en "dur" dans votre application alors un changement de clé empechera tout les utilisateurs d'utiliser l'application.

L'API Pum se base sur la philosophie REST. Les appels à l'API doivent être faits sous la forme de requêtes HTTP en GET, POST, PUT, DELETE (sachant que PUT et DELETE doivent être émulé) sur le domaine api.plum.pro.

Voici le format d'un appel à l'API pour récupérer une liste d'objet :

GET http://api.plum.pro/ENTITE.(xml|json)

Et pour récupérer un seul objet :

GET http://api.plum.pro/ENTITE/ID.(xml|json)

où :
ID : Identifiant unique de l'objet ENTITE à récuperer. Exemple : 2.
(xml|json) : Le format des objets ENTITE à récuperer.
GET : Type d'appel à l'API.
ENTITE : Nom de l'entité appelé. Exemple : "tâche".

Le format de retour d'un objet est en XML ou JSON. Voici un retour sous la forme XML d'un objet :
<ENTITE> ( ... réponse ... ) </ENTITE> où :
ENTITE : Nom de l'entité appelé. Dans notre exemple cela sera : "tâche".

Et en JSON :
{"ENTITE":{( ... réponse ... )}}

La suite de la documentation ne prendra en compte que la forme XML car il s'agit de la forme la plus utilisée par les développeurs.


Lorsque le retour est valide et que vous demandez une liste d'objets (par exemple la liste de toutes les tâches) alors le retour sera englobé dans une balise supplémentaire : <ENTITES>Retour classique XML</ENTITES>.

Voici le format de retour d'une liste d'objets :
<ENTITES> <ENTITE> ( ... réponse ... ) </ENTITE> <TotalENTITE>12</TotalENTITE> </ENTITES> où :
ENTITES : Nom de la liste d'entité appelé. Exemple : "taches" avec un "s".
TotalENTITE : Nombre total d'objet retourné par l'API. Exemple : "TotalTache"

Enfin il existe un dernier format : le format d'erreur
<Errors> <Error> <Code>Code d'erreur</Code> <Message>( ... réponse ... )</Message> </Error> </Errors> où :
Code : le code d'erreur défini dans le chapitre "Erreurs".
Message : La description de l'erreur. En français pour le haut niveau et en anglais pour le bas niveau.
On remarque également la même syntaxe que les listes d'objets mais avec cette fois "Errors" qui contient "Error".

Nous avons vu l'utilisation de l'API en GET afin de récupérer soit une liste d'objet soit un objet (ou hélas cela arrive un message d'erreur). Il reste maintenant à voir comment on modifie ou supprime un objet grâce à l'API.

La modification d'un objet ou sa suppression ainsi que la création d'objet sont des actions qui doivent être réalisées sous d'autres types d'appel à l'API.

Voici le schéma simplifié de la base de données accessible par l'API : (schéma du 5 juillet 2011)