Commencer 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 à 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 de CSO, ni à la taille de l'ensemble de données à échanger. Cependant, à un moment donné, CSO ou l'autre système ne sera pas en mesure de traiter les demandes efficacement. La bonne pratique consiste à utiliser des opérateurs de décalage et de limitation pour réduire les temps de réponse ou pour envoyer de grandes quantités de données en 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 de la https:// protocole. Les données à échanger, le ressource est désigné par le nom du type de données ou de l'objet qui le détient (marché, événement, fiche d'informations, 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 léger basé sur du texte, couramment utilisé pour les transferts de données entre systèmes. Bien que développé principalement pour les applications JavaScript, JSON est indépendant du langage de programmation, et les analyseurs et 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 assuré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 demandes API, X-CSO-API-KEY, et l'en-tête Accepter 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'informations avec l'ID 342333 dans l'événement avec l'ID 12312224 ressemblerait à ceci :

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

Plusieurs demandes peuvent être nécessaires 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'informations dans cet événement pour obtenir l'ID de la fiche d'informations particulière à partir de laquelle vous avez besoin d'informations sur les champs. Le système externe peut être capable de stocker ces ID, pour permettre l'accès à des champs et/ou des lignes de faits dans une seule demande.

L'utilisation de l'un des champs d'informations pour contenir un horodatage, un numéro de séquence de mise à jour ou un autre type d'indicateur vous permet de demander uniquement les nouvelles données depuis la dernière mise à jour pour éviter les problèmes de performance.

Méthodes de demande

GET (données en lecture)

La demande GET interroge la base de données CSO et renvoie les informations correspondant à la demande 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é par la limite à partir de là.

Exemple : https://{name_of_cso_site}/api/markets?offset=10&limit=5 renvoie les 5 marchés suivants à 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 sera retourné.

PUT (Actualiser les données)

La demande PUT introduit 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 l'api/markets met à jour tous les marchés spécifiés (par leur ID) dans le corps de la demande.

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

POST (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. En cas de réussite, le nouvel ID des données/ressources est renvoyé.

DELETE (Supprimer données)

La suppression de données est prise en charge pour certains types de ressources, mais pas tous. Cela peut être fait sur une ressource à la fois, ou comme une opération en vrac. 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 DELETE avec beaucoup de soin et d'attention.

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 de réussite général. Les demandes POST incluaient également le code 201 qui indique la réussite 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 édités pour éviter les conflits de noms, etc., les réponses d'une demande GET peuvent dans la plupart des cas être soumises dans les corps d'une demande PUT ou POST. Dans le cas où 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 traiter des quantités massives de données, vous ne serez intéressé que par un sous-ensemble des données récupérées par votre demande GET. L'API CSO prend en charge Coupa opérateurs API standard 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érez tous les marchés dont le nom contient le texte « européen », le cas échéant.

GET on https://{name_of_cso_site}/api/markets?name[contains]=european

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

GET on https://{name_of_cso_site}/api/markets?name[starts_with]=FTL

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

GET on https://{name_of_cso_site}/api/markets?name[ends_with]=2018

Récupérer les 50 premiers événements avec des noms incluant 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 descriptive, etc.) ainsi que les demandes autorisées pour chacun d'eux. Cliquer sur une demande ouvre un schéma qui décrit le format JSON.

Exemples pour référence

Obtenir des marchés

ACCÉDER À https://{name_of_cso_site}/api/markets

Code de réponse : 200

Corps de la réponse :

{

"total" : 70,

"markets" : [

{

"id" : "9219593111199654844",

"name" : "Market A",

"description" : "A descriptive text."

},

{

"id" : "9219593111199654844",

"name" : "Market B"

},

... 68 marchés en plus.

]

}

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 lorsque vous utilisez JSON.

Créer un marché

POST vers https://{name_of_cso_site}/api/markets

Corps de la demande :

{

"name" : "First Market",

"description" : "Optional text that describes the market."

}

Code de réponse : 201

Corps de la réponse :

{

"result" : [

{

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

"description" : "1 objects created."

}

],

"added" : 1,

"markets" : [

{

"id" : "9219593535573352536"

}

]

}

Le corps de réponse inclut l'ID créé par CSO pour le nouveau marché.

Actualiser un marché

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

Corps de la demande :

{

"name" : "First Market with updated name"

}

Code de réponse : 200

Corps de la réponse :

{

"result" : [

{

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

"description" : "1 objects updated."

}

],

"updated" : 1

}

L'attribut « update » contient le nombre d'objets mis à jour par la demande PUT.