API: vue d'ensemble

À propos de ce document

Ce document décrit l'API Symplify et la façon de commencer à l'utiliser. Vous devez être familier avec l'interface graphique de Symplify afin de bien comprendre toutes les composantes de ce document.

L'API utilise la méthodologie REST. Un bref aperçu des services web RESTful peut être trouvé ici (anglais) : http://net.tutsplus.com/tutorials/other/a-beginners-introduction-to-http-and-rest/


À propos de la documentation de l'API

Symplify utilise une bibliothèque tierce appelée Swagger pour documenter l'API REST. Cette documentation est construite sur la base du code réel et cela devrait garantir que la documentation sera toujours à jour. Il n'y aura pas de version imprimée de l'API ; la version accessible via le lien est la version la plus récente et la plus actuelle.

​Ressources en ligne

Vous trouverez la version en ligne de l'API à l'adresse suivante :

http://www<server>.carmamail.com/mail/swagger

Si vous avez des identifiants d'utilisateur pour Symplify, vous pouvez en fait accéder à vos données et les mettre à jour en utilisant les méthodes décrites sur la page de présentation Swagger.

Pour ce faire, vous devez utiliser la page swagger du serveur sur lequel se trouve votre compte, vous connecter à Symplify et trouver votre serveur dans le menu principal en bas.

Si vous vous connectez normalement à Symplify en utilisant le URL: http://www2.carmamail.com/carma vous pouvez accéder à vos données depuis le URL http://www2.carmamail.com/mail/swagger.

Veuillez noter qu'il s'agit de vos données en direct, donc toute mise à jour que vous ferez modifiera les paramètres des autres utilisateurs de votre compte, donc utilisez les fonctions POST/PUT et SUPPRIMER avec précaution.

Évolution de l'API

Nous nous efforcerons de maintenir la rétrocompatibilité de l'API. Ceci s'applique à tous les appels API qui ne sont pas explicitement marqués comme brouillon ou POUR UTILISATION INTERNE SEULEMENT dans la documentation Swagger. Cela signifie que :

  1. Les URI des ressources ne changeront pas.
  2. Les noms des champs de données dans les demandes et les réponses du corps du message ne changeront pas.
  3. Les champs de données dans les demandes et les réponses du corps du message ne seront pas supprimés.
  4. De nouveaux champs optionnels dans les demandes et les réponses du corps du message pourraient être ajoutés à l'avenir. Les systèmes d'intégration devraient en tenir compte, en particulier lorsqu'ils consomment des réponses de l'API REST.
  5. De nouvelles ressources seront ajoutées à mesure que de nouvelles fonctionnalités seront mises à la disposition du public.
  6. Si des modifications incompatibles sont nécessaires dans les ressources existantes, les anciennes resteront disponibles, sauf si les conditions énoncées au point 7 s'appliquent.
  7. Dans certains cas très inhabituels, des changements internes dans le système peuvent rendre les ressources existantes obsolètes ou insuffisantes pour la tâche qu'elles étaient initialement prévues. Dans ces cas, la ressource originale sera laissée en place, mais sera modifiée pour renvoyer le code de réponse HTTP 410 (Gone), avec un corps de réponse comprenant des informations sur la raison.


Customer Id

Vous devez toujours inclure votre ID client lorsque vous appelez une ressource Symplify. Connectez-vous à Symplify et trouvez votre ID client dans le menu principal en bas.


Syntaxe

Pour la plupart des ressources, il y a cinq méthodes que vous pouvez appeler ; get all, get one, create one, update one et delete one. La syntaxe est pratiquement la même pour toutes les ressources, vous devriez donc être capable de vous faire une idée générale assez rapidement.

La structure de l'URI ressemble généralement à ceci :

<server>/rest/{customerid}/<resource>/[{id}]

server: https://www<x>.carmamail.com où X est le numéro de votre serveur

customerId : votre numéro de client.

ressource : la ressource que vous voulez utiliser

id : l'ID (s'il y a lieu) de l'élément que vous voulez ajouter/mettre à jour/gérer/supprimer. 

Exemple :

<server>/rest/{customerid}/reports/campaigns/{id}

 

Type de support

Toutes les données fournies à l'API REST et reçues de celle-ci utilisent le type de support application/json. Pour assurer une compatibilité totale, veuillez vous assurer que:

Toutes les demandes GET incluent l'en-tête
Accept: application/json

Toutes les demandes PUT et POST incluent les en-têtes suivants:
Accept: application/json
Content-Type: application/json

Toutes les données envoyées à l'API sont censées être dans le jeu de caractères standard application/json UTF-8, sauf indication contraire explicite sous forme de paramètre de jeu de caractères dans l'en-tête Content-Type. Toutes les données envoyées en réponse à l'API seront dans le jeu de caractères UTF-8.

Types de demandes


Get All

Pour obtenir toutes les données, vous envoyez une demande GET sans identifiant, par exemple.

GET https://www<server>.carmamail.com/rest/<customerId>/projects
Accept: application/json

Get One(un seul)

Pour obtenir une donnée, vous envoyez une demande GET avec un identifiant, par exemple.

GET https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>​
Accept: application/json

Créer Un

Pour créer de nouvelles données, vous allez émettre une demande POST sans identifiant. Généralement, la création d’une nouvelle entité nécessite l’inclusion de données dans l’organe du message, par exemple:

POST https://www<server>.carmamail.com/rest/<customerId>/projects
Accept: application/json
Content-Type: application/json
Content-Length: …
<entité à créer en JSON>

​​

Mise à jour de Un

Pour mettre à jour une donnée, vous émettez une demande PUT avec l'id et les données devant être utilisées pour mettre à jour l'entité:

​PUT https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>
Accept: application/json
Content-Type: application/json
Content-Length: …
​<entity to update as JSON>

Supprimer Un

Pour supprimer, envoyer une requête DELETE avec un identifiant, c.-à-d.

DELETE https://www<server>.carmamail.com/rest/<customerId>/projects/<projId>

api-1.png


Test des demandes

Vous pouvez tester une demande directement dans l'interface Swagger en saisissant vos informations d'identification, votre numéro de client et d'autres données nécessaires à la méthode

Informations d'identification

Pour les tests, vous pouvez utiliser les mêmes informations d'identification que celles que vous utilisez pour vous connecter à Symplify. Pour des raisons de sécurité, nous vous recommandons de ne pas utiliser vos propres identifiants en production. La recommandation pour la production est d'obtenir un utilisateur API spécial pour votre compte et d'utiliser ces identifiants. Vous pouvez demander un utilisateur API en envoyant un courriel à support@symplify.com.

 ​

Requêtes GET

Les requêtes GET sont utilisées pour extraire des données du système.

Si, par exemple, vous souhaitez récupérer tous vos projets, vous devez d’abord les développer:

api-2.png
Vous cliquez ensuite sur la dernière entrée pour la développer, elle vous montrera la vue suivante:

api-3.png
Si vous entrez votre numéro de client et cliquez sur Essayez-le, on vous demandera vos informations d'identification. Entrez-les et cliquez sur ok, et vous obtiendrez une réponse formatée en JSON avec les informations sur vos projets.

api-4.png

Requêtes POST

Les requêtes POST sont utilisées pour créer des données dans le système.

Lors de l'émission d'un POST, vous devez souvent fournir un corps de message au format JSON contenant les données de l'entité que vous créez. Vous pouvez voir la syntaxe du modèle qui sera renvoyé en cliquant sur Schéma du modèle pour la méthode POST.

api-5.png


Pour émettre un POST, vous pouvez obtenir le schéma de saisie en cliquant sur Schéma de modèle pour la ressource.

api-6.png
Copiez le schéma dans la zone de saisie, en cliquant sur le texte sous la case jaune et complétez les informations requises.

Note ! Vous ne devez pas inclure les champs "id", "dateCreated" ou "dateModified" car ils sont créés automatiquement par le serveur. Vous pouvez supprimer en toute sécurité les champs pour lesquels vous n'avez pas de données, par exemple si vous n'avez pas de données pour Contact.MiddleName, ce champ peut être supprimé de la structure de saisie Json. Vous obtiendrez une erreur de validation si vous supprimez un champ obligatoire.

Requêtes PUT

Les requêtes PUT sont utilisées pour la mise à jour des données dans la base de données. Le corps du message doit inclure les données nécessaires à la mise à jour de l'entité. Pour certaines ressources, il suffit de spécifier les champs que vous modifiez, mais en général, vous devez vous assurer d'inclure tous les champs tels qu'ils ont été reçus d'une requête GET précédente (encore une fois, les champs id, dateCreated et dateModified ne sont pas requis. Le champ Id est spécifié dans l'URI et les autres sont créés/mis à jour automatiquement).

api-7.png


Requêtes DELETE

Pour supprimer une entrée, vous devez fournir l'identifiant du client et l'identifiant des données à supprimer.

api-8.png


Description du domaine

Toutes les méthodes dans Symplify font partie d'un domaine, en dessous les domaines sont listés avec une brève description des méthodes et un lien vers la documentation du domaine.

Le lien pointe vers le serveur 3, mais vous pouvez facilement remplacer la première partie du nom de domaine afin d'accéder à votre serveur.

Cet article vous a-t-il été utile?
Utilisateurs qui ont trouvé cela utile : 0 sur 0