Démarrez avec CSO OpenAPI

L'API CSO vous permet de créer, de mettre à jour et de récupérer des données dans et à partir de CSO. La configuration des appels API fait partie du projet d'intégration de CSO avec un système tiers pour permettre l'échange de données entre les systèmes.

Il n'y a pas de limite technique ni au nombre de demandes envoyées à l'API REST CSO, ni à la taille de l'ensemble de données à échanger. Cependant, à un moment donné, l'OSC ou l'autre système ne sera pas en mesure de traiter efficacement les demandes. La bonne pratique consiste à utiliser des opérateurs de décalage et de limite pour réduire les temps de réponse ou à envoyer de grandes quantités de données par petits morceaux.

Terminologie et syntaxe

Tous les appels API pour échanger des données entre CSO et une autre base de données sont effectués à l'aide du protocole https ://. Les données à échanger, la ressource, sont désignées par le nom du type de données ou de l'objet qui les contient (marché, événement, fiche d'information, etc.) suivi de l'ID de l'objet ou de l'ensemble de données particulier dans CSO, le cas échéant, au format suivant :

https ://{name_of_cso_site}/api/{resource_name}/{resource_id}

Le nom d'un site CSO client serait {company_name}.cso.coupahost.com. Notez que l'appel API utilise l'ID pour spécifier une ressource, et non le nom réel ou l'objet ou l'ensemble de données.

Les appels API sont écrits au format JSON (JavaScript Object Notation). Il s'agit d'un format standard ouvert basé sur du texte léger couramment utilisé pour les transferts de données entre les systèmes. Bien qu'il soit développé principalement pour les applications JavaScript, JSON est agnostique au langage de programmation, et des analyseurs et d'autres outils sont disponibles pour la plupart des langages.

Authentification

L'authentification pour l'échange de données entre le serveur CSO et un serveur tiers est médiatisée par une clé API unique. La clé API est générée par Coupa. Il est stocké dans CSO et associé à un utilisateur API. La clé API est incluse dans l'en-tête de toutes les requêtes API, X-CSO-API-KEY, et l'en-tête Accept doit être défini avec la valeur ‘application/json’.

Demandes

Suivant la syntaxe décrite ci-dessus, une demande à l'API CSO pour les champs dans une fiche d'information avec l'ID 342333 dans le cas avec l'ID 12312224 ressemblerait à ce qui suit :

https ://{name_of_cso_site}/api/events/12312224/fact-sheets/342333/fields

Il peut falloir plusieurs demandes pour obtenir un ensemble de données particulier, par exemple, récupérer d'abord les événements pour pouvoir obtenir un ID d'événement particulier, puis obtenir les fiches d'information même pour obtenir l'ID de la fiche d'information particulière à partir de laquelle vous avez besoin d'informations sur les champs. Le système externe peut être en mesure de stocker ces ID :s, pour permettre l'accès aux champs et/ou aux lignes de faits dans une seule demande.

L'utilisation de l'un des champs Fact pour conserver un horodatage, un numéro de séquence de mise à jour ou un autre type d'indicateur vous permet de n'interroger que les nouvelles données depuis la dernière mise à jour pour éviter les problèmes de performances.

Demander des méthodes

GET (Lire les données)

La requête GET interroge la base de données CSO et renvoie les informations correspondant à la requête au système tiers. Le nombre d'objets retournés est limité à 250. La réponse peut être affinée en ajoutant des paramètres de demande :

• Limite : spécifie le nombre d'objets à renvoyer ;
• Décalage : spécifie la position de départ dans l'ensemble de données trouvé, pour renvoyer le nombre de lignes spécifiées par limite à partir de là.

Exemple : https ://{name_of_cso_site}/api/markets ?offset=10&limit=5 renvoie les 5 prochains marchés à partir de la position 10 dans la liste des marchés trouvés dans CSO. S'il y a moins de 15 marchés, moins ou aucun ne sera retourné.

PUT (METTRE à jour les données)

La demande PUT apporte les données du système tiers dans CSO pour mettre à jour les données existantes.

Exemple : api/markets/{id} met à jour le marché avec l'ID donné, tandis que api/markets met à jour tous les marchés spécifiés (par leur ID :s) dans le corps de la requête.

Les mises à jour sont effectuées de manière indulgente, c'est-à-dire que si la mise à jour d'une ressource échoue, les autres pourraient réussir.

PUBLIER (créer ou insérer des données)

Une demande POST crée ou insère des données dans CSO dans la ressource spécifiée. Si elle réussit, le nouvel ID des données/ressources est renvoyé.

SUPPRIMER (Supprimer les données)

La suppression de données est prise en charge pour certains types de ressources, mais pas pour tous. Cela peut être fait sur une ressource à la fois ou en tant qu'opération groupée. Notez que les données sont complètement et définitivement supprimées et ne peuvent pas être recréées dans CSO. En d'autres termes, utilisez la méthode de SUPPRESSION avec beaucoup de soin et de pleine conscience.

Réponses

Les réponses de l'API CSO comprennent un code de réponse et un corps JSON.

Le code 200 est l'indicateur général de succès. LES demandes de PUBLICATION comprenaient également le code 201 qui indique le succès de la création des données demandées.

Les erreurs entraînent des codes de réponse 4xx. L'erreur est généralement déclenchée par des appels qui ne sont pas pris en charge ou autorisés. Les demandes qui échouent pour des raisons inconnues renvoient le code 500. Si une demande échoue, n'essayez pas de la soumettre à nouveau – elle échouera à nouveau. Vous trouverez plus de détails sur les codes de réponse ici.

Bien que certains paramètres puissent avoir besoin d'être modifiés pour éviter les collisions de noms, etc., les réponses d'une demande GET peuvent dans la majorité des cas être soumises dans le corps d'une demande PUT ou POST. Si le format d'un type de données particulier n'est pas connu, vous pouvez donc exploiter l'API pour vous fournir le format correct.

Opérateurs API

Bien que CSO puisse gérer des quantités massives de données, il se peut que vous ne soyez intéressé que par un sous-ensemble des données récupérées par votre demande GET. L'API CSO prend en charge les opérateurs d'API standard Coupa, ce qui vous permet de filtrer les données pertinentes. Les opérateurs peuvent être combinés pour affiner les réponses. Notez que toutes les conditions doivent correspondre pour récupérer un objet ou un point de données particulier.

Exemples d'utilisation d'opérateurs pour filtrer le résultat

Récupérer le marché avec le nom A, s'il existe :

GET on https ://{name_of_cso_site}/api/markets ?name=A

Récupérer tous les marchés dont les noms contiennent le texte « européen », le cas échéant.

ALLEZ sur https ://{name_of_cso_site}/api/markets ?name[contains]=european

Récupérer tous les marchés dont les noms commencent par « FTL », le cas échéant :

ALLEZ sur https ://{name_of_cso_site}/api/markets ?name[starts_with]=FTL

Récupérer tous les marchés dont les noms se terminent par « 2018 », le cas échéant :

ALLEZ sur https ://{name_of_cso_site}/api/markets ?name[ends_with]=2018

Récupérer les 50 premiers événements avec les noms, y compris le « LTL », le cas échéant :

GET on https ://{name_of_cso_site}/api/events ?limit=50&name[contains]=LTL

Documentation

Le schéma OpenAPI est disponible sur tous les sites CSO à l'adresse https ://{name_of_cso_site}/openapi.html. La documentation répertorie les objets et les types de données accessibles (marché, utilisateur, fiche d'information, etc.) et les demandes autorisées pour chacun d'entre eux. En cliquant sur une demande, vous ouvrez un schéma qui décrit le format JSON.

Exemples pour référence

Obtenir des marchés

ACCÉDEZ à https ://{name_of_cso_site}/api/markets

Code de réponse : 200

Corps de la réponse :

{

"total" : 70,

"marchés" : [

{

"id" : "9219593111199654844",

"nom" : "Marché A",

"description" : "Un texte descriptif."

},

{

"id" : "9219593111199654844",

"nom" : "Marché B"

},

… 68 autres marchés.

]

}

Notez que la description est laissée de côté pour le marché B. Les valeurs vides ou nulles ne sont pas censées être envoyées lors de l'utilisation de JSON.

Créer un marché

PUBLIER sur https ://{name_of_cso_site}/api/markets

Corps de la demande :

{

"name" : "Premier marché",

"description" : "Texte facultatif qui décrit le marché."

}

Code de réponse : 201

Corps de la réponse :

{

"result" : [

{

"type" : "api.post.added",

"description" : "1 objets créés."

}

],

"ajouté" : 1,

"marchés" : [

{

"id" : "9219593535573352536"

}

]

}

Le corps de la réponse inclut l'identifiant créé par CSO pour ce nouveau marché

Mettre à jour un marché

METTRE en https ://{name_of_cso_site}/api/markets/{market_id}

Corps de la demande :

{

"nom" : "Premier marché avec nom mis à jour"

}

Code de réponse : 200

Corps de la réponse :

{

"result" : [

{

"type" : "api.put.updated",

"description" : "1 objets mis à jour."

}

],

"mis à jour" : 1

}

L'attribut « mis à jour » contient le nombre d'objets mis à jour par la requête PUT.