Definir una especificación de la API para un servicio externo

Objetivos de aprendizaje

Después de completar esta unidad, podrá:

• Describir la finalidad de la especificación de la API.
  
• Explicar los elementos de una definición de esquema de servicios externos compatible.
  
• Indicar tres problemas que pueden generar un error en la especificación de la API.
  

¿Por qué necesita una definición de esquema?

En la unidad anterior, aprendió que una especificación de la API es un archivo que contiene el esquema descriptivo que define lo que puede hacer una API. Tanto si es usted quien crea una especificación de la API para su registro en Servicios externos como otra persona, es útil entender su finalidad y cómo se utiliza. 

Imagine que tiene la API de un banco basada en REST. Necesita un formato común estandarizado para describir la estructura de la API basada en REST de dicho banco. Ingrese la especificación de la API. Salesforce utiliza la especificación OpenAPI comúnmente adoptada para el formato de descripción. 

Su especificación de la API contiene una definición de esquema que describe los tipos de entradas y salidas que puede incluir en las llamadas (o solicitudes) que su organización realice al servicio web externo. Por ejemplo, sus llamadas podrían incluir un Id. como entrada numérica o un name (nombre) como salida de texto.

Además, su especificación de la API contiene la información de extremo y los parámetros de autenticación para los servicios web de la API basada en REST a los que puede acceder. (Recuerde que el extremo expone los recursos de servicios web con los que interactúan los servicios externos). Por ejemplo, esta especificación de la API del servicio web de un banco ficticio incluye métodos para agregar y eliminar cuentas bancarias: https://th-external-services.herokuapp.com/accounts/schema.

En una aplicación del mundo real, de acuerdo con las mejores prácticas de seguridad, se incluiría un paso de autenticación antes de acceder a la API de un banco.

Como la especificación de la API de nuestro banco ficticio se compone de datos estructurados y legibles para el ser humano, veámosla.

Estas son las operaciones de cuenta básicas del esquema.

Este es un fragmento de código parcial del esquema de la especificación de la API que contiene información sobre un método GET. Por si no lo sabía, un método GET simplemente recupera información de los recursos de un servicio web. Este método GET en concreto recupera (“obtiene”) información sobre una cuenta mediante la ruta del recurso (en este caso, /accounts/{accountName}), donde {accountName} es una cuenta especificada. Si mira debajo de "parameters", puede ver "name":"accountName". Este parámetro debe coincidir con el nombre de la cuenta que especifique y es obligatorio ("required":true). Además, debe tener la forma de una cadena.

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

Esta es solo una parte de una definición de esquema mucho más amplia. No obstante, puede observar que aunque está diseñado para el consumo por parte de los servicios externos, es también legible para el ser humano. Además, tiene un formato lógico que permite a Servicios externos procesar las operaciones para mostrarlas como acciones invocables en herramientas como Flow Builder o Einstein Bots. 

Los siguientes pasos le muestran cómo registrar de forma declarativa su especificación de la API. Sin embargo, veamos primero los elementos que hacen que una definición de esquema sea válida y compatible; es decir, las descripciones detalladas de cada función de la API por separado que se incluyen en el documento de la especificación de la API.

¿Cómo se logra que un esquema sea válido y compatible?

Ya sabemos en qué consiste la especificación de la API. Pero ¿qué queremos decir con un esquema válido y compatible? 

Existen requisitos de validación de esquemas definidos por la especificación OpenAPI y requisitos de esquema específicos de Servicios externos. Servicios externos puede admitir su esquema de forma apropiada y llamar a su servicio web cuando se cumplen ambos requisitos.  

Un manual de la validación de esquemas

Aunque un esquema es legible para el ser humano, también debe ser legible para una computadora. Debe seguir una estructura lógica de modo que Servicios externos puedan consumirlo fácilmente. Un esquema estructurado incorrectamente significa que el servicio web externo no puede comunicar (devuelve mensajes de error y excepción) y, por último, Servicios externos no pueden introducirlo. Cumplir con las restricciones estructurales, lógicas y de sintaxis es un primer paso necesario para la validación de esquemas. La especificación OpenAPI define estas reglas generales y elimina las conjeturas de llamar a un servicio web externo.

Esquema de servicios externos compatible 

Además de directrices de OpenAPI generales para la validación de esquemas, también existen limitaciones de esquema específicas de Servicios externos. Recomendamos revisar estos requisitos antes de registrar su especificación de la API con Servicios externos. Un esquema compatible con Servicios externos significa que su esquema es válido de acuerdo con la especificación OpenAPI y que, además, cumple con los requisitos específicos de Servicios externos. Por ejemplo, una especificación de la API puede generar un error en el proceso de registro si excede el límite de tamaño del archivo o supera el límite de la cantidad total de acciones u objetos permitidos.

Si desea ver una lista de requisitos clave para la creación de un esquema compatible de Servicios externos, consulte Ayuda de Salesforce: Consideraciones de Servicios externos. 

Recursos

• Ayuda de Salesforce: Esquema de servicios externos
• Ayuda de Salesforce: Consideraciones de servicios externos
• Sitio externo: Swagger Open API 2.0
• Desarrollador de Salesforce: Palabras reservadas de Apex