Definir una especificación de 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 API es un archivo que contiene el esquema descriptivo que define lo que puede hacer una API. Sea usted o no quien finalmente cree una especificación de la API para su registro en Servicios externos, es de suma utilidad comprender su objetivo y cómo se utiliza. 

Imagine que tiene una API de un banco basada en REST. Necesita un formato común estandarizado para describir la estructura de la API basada en REST de nuestro banco. Introduzca 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, si sigue las mejores prácticas de seguridad, incluiría un paso de autenticación antes de acceder a la API de un banco.

Podemos echarle un vistazo a la especificación de la API de nuestro banco ficticio, ya que se compone de datos estructurados y legibles para el ser humano.

Estas son las operaciones de cuenta básicas de nuestro 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 concreta. 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ñada para ser utilizada en Servicios externos, también es 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 Bots de Einstein. 

Los siguientes pasos le muestran cómo registrar de forma declarativa su especificación de la API. Sin embargo, antes, vamos a ver 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.

¿Qué hace que un esquema sea válido y compatible?

Ya sabemos en qué consiste la especificación de la API. Ahora bien, ¿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 podrá admitir su esquema de forma apropiada y llamar a su servicio web cuando se cumplan 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 un ordenador. Debe seguir una estructura lógica de modo que Servicios externos puedan consumirlo fácilmente. Un esquema mal estructurado implica que el servicio web externo no puede comunicarse (devuelve mensajes de error y excepción) y, por último, que Servicios externos no puede procesarlo. 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 sobre las llamadas 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. Que un esquema sea 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 supera el límite de tamaño del archivo o supera el límite de la cantidad total de acciones u objetos permitidos.

Para ver una lista de requisitos clave para la creación de un esquema compatible de Servicios externos, consulte la 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 clave reservadas de Apex