Definir uma especificação de API para um serviço externo

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

• Descrever o objetivo da especificação da API.
  
• Explicar os elementos de uma definição de esquema de Serviços externos com suporte.
  
• Nomear três problemas que podem fazer com que sua especificação da API falhe.
  

Por que você precisa de uma definição de esquema?

Na unidade anterior, você aprendeu que uma especificação de API é um arquivo que contém o esquema descritivo que define o que uma API pode fazer. Independentemente de ser você a pessoa que cria uma especificação de API para o registro de Serviços externos, é útil entender seu objetivo e como ela é usada. 

Imagine que você tenha uma API de banco baseada em REST. Você precisa de um formato comum e padronizado para descrever a estrutura da API baseada em REST do seu banco. Digite a especificação da API. O Salesforce usa a especificação OpenAPI comumente adotada como o formato de descrição. 

Sua especificação da API contém uma definição de esquema que descreve os tipos de entradas e saídas que você pode incluir nas chamadas, ou solicitações, que sua organização faz ao serviço Web externo. Por exemplo, suas chamadas podem incluir uma ID como entrada numérica ou um name (nome) como saída de texto.

Sua especificação da API também contém as informações de ponto de extremidade e os parâmetros de autenticação para os serviços Web de API baseada em REST que você pode acessar. (Lembre-se de que o ponto de extremidade é simplesmente o que expõe os recursos de serviços da web com os quais os Serviços Externos precisam interagir.) Por exemplo, essa especificação da API de serviço Web de um banco fictício inclui métodos para adicionar e excluir contas: https://th-external-services.herokuapp.com/accounts/schema.

Em um aplicativo do mundo real, seguindo as melhores práticas de segurança, você incluiria uma etapa de autenticação antes de acessar a API de um banco.

Como a especificação de API do seu banco fictício é de dados estruturados que podem ser lidos por humanos, vamos analisá-la.

Aqui estão as operações de conta básicas do seu esquema.

Veja um trecho de código do esquema da especificação da API que contém informações sobre um método GET. Se você não sabe, um método GET simplesmente recupera informações de recursos de um serviço Web. Esse método GET em particular recupera informações sobre uma conta usando o caminho do recurso, neste caso, /accounts/{accountName}, em que {accountName} é uma conta especificada. Se você olhar em "parameters", poderá ver "name":"accountName". Esse parâmetro deve corresponder ao nome da conta que você especificou e é obrigatório ("required":true). Ele também deve assumir a forma de uma sequência de caracteres.

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

Essa é apenas uma parte de uma definição de esquema muito maior. Mas você pode ver que, embora seja projetado para consumo pelos Serviços externos, ele também pode ser lido por pessoas. Ele também é formatado de forma lógica que permite que os Serviços externos processem as operações para revelá-las como ações invocadas em ferramentas como o Flow Builder ou os Bots do Einstein. 

Os próximos passos mostram como registrar declarativamente sua especificação da API. Mas primeiro, vamos cobrir os elementos que compõem uma definição de esquema válida e com suporte; as descrições detalhadas de cada capacidade de API separada contidas no documento de especificação da API.

O que faz um esquema válido e com suporte?

Agora sabemos do que se trata uma especificação da API. Mas o que queremos dizer com um esquema válido e com suporte? 

Há requisitos de validação de esquema que a especificação OpenAPI define e também há requisitos específicos de esquema de Serviços externos. Os Serviços externos podem dar suporte adequado ao seu esquema e chamar seu serviço Web quando esses dois requisitos são atendidos.  

Uma introdução sobre validação de esquema

Embora um esquema possa ser lido por pessoas, ele também deve poder ser lido por máquina. Ele precisa seguir uma estrutura lógica para que os Serviços externos possam consumi-lo facilmente. Um esquema estruturado incorretamente significa que o serviço Web externo não pode se comunicar (retorna mensagens de erro e exceção) e, por fim, os Serviços externos não podem ingeri-lo. O atendimento a restrições estruturais, lógicas e de sintaxe é uma primeira aprovação necessária da validação de esquema. A especificação OpenAPI define essas regras gerais e remove as dúvidas em chamar um serviço Web externo.

Esquema de Serviços externos com suporte 

Além das diretrizes gerais do OpenAPI para validação de esquema, existem também limitações de esquema específicas aos Serviços externos. É melhor examinar esses requisitos antes de registrar sua especificação da API nos Serviços externos. Um esquema com suporte pelos Serviços externos significa que seu esquema é válido de acordo com a especificação OpenAPI e também atende aos requisitos de Serviços externos específicos. Por exemplo, uma especificação da API poderá falhar no processo de registro se exceder a limitação de tamanho do arquivo ou o limite do número total de objetos ou ações.

Para uma lista de requisitos principais para criar um esquema com suporte pelos Serviços externos, consulte a Ajuda do Salesforce: Considerações sobre Serviços externos. 

Recursos

• Ajuda do Salesforce: Esquema de serviços externos
• Ajuda do Salesforce: Considerações sobre Serviços externos
• Site externo: Swagger Open API 2.0
• Desenvolvedor do Salesforce: Palavras-chave reservadas do Apex