Définition d’une spécification d’API pour un service externe

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

• Décrire l’utilité d’une spécification d’API
• Présenter les éléments constitutifs d’une définition de schéma de services externes pris en charge
• Nommer trois problèmes pouvant entraîner des échecs en lien avec votre spécification d’API

Pourquoi avez-vous besoin d’une définition de schéma ?

Dans l’unité précédente, vous avez appris qu’une spécification d’API est un fichier contenant le schéma descriptif qui définit ce qu’une API peut faire. Que vous soyez ou non la personne qui élaborera la spécification d’API dans le cadre de votre enregistrement au sein de l’outil Services externes, il est important de comprendre son utilité et la manière dont elle est employée. 

Imaginez que vous ayez une API bancaire de type REST. Vous avez besoin d’un format commun et standardisé pour décrire la structure de notre API bancaire de type REST. C’est à cela que sert une spécification d’API. Salesforce utilise la spécification OpenAPI, adoptée à grande échelle, pour le format de description. 

Votre spécification d’API contient une définition de schéma mentionnant les types d’entrées et de sorties que vous pouvez inclure dans les appels ou requêtes que votre organisation envoie au service externe. Par exemple, vos appels peuvent inclure une entrée numérique, comme un ID (identifiant), ou une sortie au format texte, comme un name (nom).

Votre spécification d’API contient également les informations relatives au point de terminaison et les paramètres d’authentification pour les services Web des API s’appuyant sur REST auxquels vous pouvez accéder (n’oubliez pas que le point de terminaison expose les ressources des services Web avec lesquelles l’outil Services externes interagit). Par exemple, la spécification d’API suivante, relative au service Web d’une banque fictive, contient des méthodes d’ajout et de suppression de comptes bancaires. https://th-external-services.herokuapp.com/accounts/schema

Dans un contexte réel, pour respecter les bonnes pratiques en matière de sécurité, vous incluriez une étape d’authentification avant de permettre l’accès à l’API d’une banque.

Puisque la spécification d’API de votre banque fictive est constituée de données structurées lisibles par l’utilisateur, examinons-la ensemble.

Voici les opérations de compte de base de votre schéma.

Voici un extrait de code partiel issu du schéma de la spécification d’API qui contient des informations sur une méthode GET. Si vous ne les connaissez pas, sachez que les méthodes GET servent simplement à récupérer des informations de ressource à partir d’un service Web. Cette méthode GET en particulier récupère (d’où son nom « get », signifiant obtenir) des informations au sujet d’un compte à l’aide du chemin de la ressource, ici /accounts/{accountName}, où {accountName} est un compte spécifié. Si vous observez ce qui est situé sous “parameters”, vous pouvez voir le code "name":"accountName". Ce paramètre doit correspondre au nom de compte que vous avez spécifié et est obligatoire, comme l’indique ("required":true). Il doit également se présenter sous la forme d’une chaîne.

"paths": {
	"/accounts/{accountName}": 
	{ "get": 
		{ "operationId": "getAccount", 
		"summary": "Retrieves an account", 
		"description": "Retrieves the account with specific name",
		"consumes": ["text/plain"], 
		"produces": ["application/json"], 
		"parameters": [{ 
		"name": "accountName", 
		"in": "path", 
		"required": true, 
		"type": "string", 
		"description": "Name of the account" }], 
		"responses": { 
			"200": { 
				"description": "The response when system finds an account with given name", 
				"schema": { 
				"$ref": "#/definitions/accountDetails" } }, "400": 
				{ "description": "Error response if the account name parameter is less than minimum characters",
			"schema": 
			{ "$ref": "#/definitions/errorModel" } }, 
			"404": { 
			"description": "Error response if the account is not supported by service or account is not found",
			"schema": { "
			$ref": "#/definitions/errorModel" 
			}

Cet extrait ne représente qu’une partie d’une définition de schéma nettement plus conséquente. Toutefois, cet aperçu vous permet de constater que bien qu’il soit conçu pour être utilisé par l’outil Services externes, cela n’empêche pas les utilisateurs de pouvoir également le lire. Elle est également formatée de manière logique, ce qui permet à l’outil Services externes de traiter les opérations afin de pouvoir les faire apparaître comme actions invocables dans des outils comme Flow Builder ou Robots Einstein. 

Les étapes suivantes vous montreront comment enregistrer de manière déclarative votre spécification d’API. Cependant, commençons par nous intéresser d’abord aux éléments qui constituent une définition de schéma valide et prise en charge, c’est-à-dire, les descriptions détaillées de chaque capacité d’API distincte contenues dans le document de spécification d’API.

Qu’est-ce qu’un schéma valide et pris en charge ?

Nous savons à présent ce qu’est une spécification d’API. Toutefois, qu’entend-on par la notion de « schéma valide et pris en charge » ? 

Il existe des exigences en matière de validation de schéma définies par la spécification OpenAPI, mais aussi des exigences de schéma propres à l’outil Services externes. Ce dernier peut prendre en charge votre schéma correctement et appeler votre service Web lorsque les deux exigences suivantes sont remplies.  

Principes de bases de la validation de schéma

Un schéma lisible par l’homme doit également être lisible par une machine. Il doit suivre une structure logique afin que l’outil Services externes puisse facilement l’exploiter. Un schéma mal structuré empêche le service Web externe de communiquer (il renvoie alors des messages d’erreur et d’exception) et au final, l’outil Services externes ne peut pas le traiter. Le respect des restrictions en matière de structure, de logique et de syntaxe est un prérequis incontournable du processus de validation de schéma. La spécification OpenAPI définit ces règles générales et permet d’appeler un service Web externe de manière certaine.

Schéma de services externes pris en charge 

En plus des instructions générales d’OpenAPI relatives à la validation de schéma, il existe également des restrictions de schéma propres à l’outil Services externes. Vous devrez vérifier que ces exigences sont bien respectées avant d’enregistrer votre spécification d’API dans l’outil Services externes. Pour que votre schéma soit pris en charge par l’outil Services externes, celui-ci doit se conformer aux exigences de la spécification OpenAPI et respecter également les exigences spécifiques de l’outil. Par exemple, le processus d’enregistrement d’une spécification d’API peut échouer si celle-ci ne respecte pas la limite de taille de fichier ou la limite du nombre total d’objets ou d’actions.

Pour obtenir la liste des exigences clés nécessaires à la création d’un schéma pris en charge par les services externes, reportez-vous à l’aide Salesforce : Considérations relatives aux services externes. 

Ressources

• Aide Salesforce : Schéma de services externes
• Aide Salesforce : Considérations relatives aux services externes
• Site externe : API ouverte Swagger 2.0
• Développeur Salesforce : Mots-clés réservés Apex