Definire una specifica API per un servizio esterno

Obiettivi di apprendimento

Al completamento di questa unità, sarai in grado di:

• Descrivere lo scopo di una specifica API.
  
• Illustrare gli elementi della definizione di uno schema di Servizi esterni supportato.
  
• Indicare tre problemi che possono provocare errori in una specifica API.
  

Perché è necessario definire uno schema?

Nell'unità precedente hai imparato che una specifica API è un file che contiene lo schema descrittivo che definisce cosa può fare un'API. Che tu sia o meno la persona che si occuperà di creare una specifica API per la registrazione in Servizi esterni, è utile comprenderne lo scopo e come viene utilizzata. 

Immagina di avere un'API bancaria basata su REST. Occorre un formato comune e standardizzato per descriverne la struttura. È qui che la specifica API entra in gioco. Salesforce utilizza le specifiche OpenAPI comunemente adottate per le descrizioni. 

Una specifica API contiene la definizione di uno schema che descrive i tipi di input e di output che si possono includere nelle chiamate, o richieste, che l'organizzazione inoltra a un servizio web esterno. Ad esempio, le chiamate possono includere un ID come input numerico o un nome come output testuale.

Una specifica API contiene inoltre le informazioni sugli endpoint e i parametri di autenticazione per i servizi web API basati su REST a cui è possibile accedere. Ricorda che l'endpoint espone le risorse dei servizi web con cui interagisce Servizi esterni. Ad esempio, questa specifica API del servizio web di una banca immaginaria include metodi per aggiungere ed eliminare conti bancari: https://th-external-services.herokuapp.com/accounts/schema.

In un'applicazione reale, in base alle best practice sulla sicurezza, l'accesso all'API di una banca sarebbe preceduto da un passaggio di autenticazione.

Dal momento che la specifica API della banca immaginaria del nostro esempio consiste di dati strutturati e leggibili dall'uomo, analizziamola.

Ecco le operazioni di base dello schema che vengono eseguite sul conto.

Di seguito è riportato uno snippet di codice parziale tratto dallo schema della specifica API che contiene informazioni su un metodo GET. Qualora non lo sapessi, un metodo GET non fa altro che recuperare da un servizio web informazioni sulle risorse. Questo particolare metodo GET recupera informazioni relative a un conto utilizzando il percorso della risorsa, in questo caso /accounts/{accountName}, dove {accountName} è il conto specificato. Se guardi sotto "parameters", vedrai "name":"accountName". Questo parametro deve corrispondere al nome del conto che hai specificato, è obbligatorio ("required":true) e deve essere di tipo stringa.

"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"
			}

Questa è solo una parte della definizione di uno schema molto più ampia. Tuttavia, noterai che, pur essendo concepita per essere utilizzata da Servizi esterni, è anche leggibile dall'uomo. Inoltre è formattata in modo logico per consentire a Servizi esterni di elaborare le operazioni ed esporle come azioni richiamabili in strumenti come Flow Builder o i bot Einstein. 

Nei prossimi passaggi mostreremo come registrare in modo dichiarativo una specifica API. Ma prima di tutto, esaminiamo gli elementi che compongono la definizione di uno schema valido e supportato: le descrizioni dettagliate di ciascuna funzionalità distinta dell'API contenute nel documento della specifica API.

Quali sono gli elementi che rendono uno schema valido e supportato?

Ora sappiamo che cos'è una specifica API. Ma cosa intendiamo per "schema valido e supportato"? 

Esistono alcuni requisiti di convalida di uno schema definiti dalle specifiche OpenAPI, ma anche requisiti specifici di Servizi esterni relativi agli schemi. Se entrambi i requisiti sono soddisfatti, Servizi esterni può supportare correttamente lo schema ed effettuare chiamate al servizio web.  

Introduzione alla convalida degli schemi

Uno schema, per quanto leggibile dall'uomo, deve essere leggibile anche da una macchina. Deve seguire una struttura logica per permettere a Servizi esterni di utilizzarlo correttamente. Uno schema strutturato in modo errato implica che il servizio web esterno non può comunicare (restituisce messaggi di errore e di eccezione) e, in definitiva, comporta l'impossibilità per Servizi esterni di importarlo. Il rispetto delle restrizioni strutturali, logiche e sintattiche è un primo passaggio necessario per la convalida dello schema. La specifica OpenAPI definisce queste regole generali ed elimina ogni incertezza riguardo alle chiamate ai servizi web.

Schema di Servizi esterni supportato 

In aggiunta alle linee guida generali di OpenAPI per la convalida degli schemi, esistono anche limitazioni per gli schemi specifiche di Servizi esterni. Prima di registrare una specifica API in Servizi esterni, dovrai esaminare questi requisiti. Uno schema supportato in Servizi esterni non solo è valido secondo le specifiche OpenAPI, ma è anche conforme ai requisiti specifici di Servizi esterni. Ad esempio, una specifica API potrebbe non superare il processo di registrazione se il file supera le dimensioni massime o se il numero totale di oggetti o azioni supera il limite.

Per un elenco dei requisiti chiave per la creazione di uno schema supportato da Servizi esterni, vedi Guida di Salesforce: Considerazioni su Servizi esterni. 

Risorse

• Guida di Salesforce: Schema di Servizi esterni
• Guida di Salesforce: Considerazioni su Servizi esterni
• Sito esterno: Swagger Open API 2.0
• Sviluppatore Salesforce: Apex Reserved Keywords (Parole chiave riservate di Apex)