Conheça as APIs da Salesforce Platform

Objetivos de aprendizagem

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

• Descrever os benefícios da abordagem de desenvolvimento API First.
• Listar casos de uso para API REST, API SOAP, API Bulk e API Pub/Sub.
• Indicar os dois tipos de limites de API e descrever como eles são calculados.

API First no Salesforce

Você está procurando pela API perfeita do Salesforce para a integração que está criando? Bem, você está prestes a navegar pelas águas da Salesforce Platform e aprender tudo sobre nossas APIs.

O panorama de APIs do Salesforce é tão vasto quanto o azul do oceano. Isso é porque o Salesforce adota uma abordagem API First para criar recursos na Salesforce Platform. A abordagem que prioriza a API (API First) consiste em criar uma API robusta para um recurso antes de focar no desenvolvimento da respectiva interface de usuário. Essa abordagem oferece a você, o desenvolvedor do Salesforce, flexibilidade para manipular seus dados como quiser.

O Salesforce sabe que seus clientes e parceiros estão sempre pensando em novas formas de estender a funcionalidade do Salesforce e em aplicativos empolgantes a criar para o AppExchange. O fornecimento de uma caixa de ferramentas abrangente para desenvolvimento na plataforma é de grande importância. Essa abordagem permite também ao Salesforce criar interfaces de usuário sobre as APIs, garantindo assim que o comportamento seja o mesmo entre elas.

Neste módulo, veremos algumas informações gerais sobre APIs, faremos uma pesquisa do conjunto de APIs do Salesforce e nos aprofundaremos no uso de algumas APIs comuns. Todas essas informações vão dar a você o conhecimento necessário para escolher a API certa para seu projeto.

APIs de dados do Salesforce

No mar das APIs do Salesforce, há um arquipélago principal de APIs normalmente usadas no qual nos concentramos neste módulo. Elas são: API REST, API SOAP, API Bulk e API Pub/Sub. Juntas, elas formam as APIs de dados do Salesforce. Seu propósito é permitir manipular seus dados do Salesforce ou assinar para conhecer alterações de dados, enquanto outras APIs permitem fazer coisas como personalizar layouts de página ou criar ferramentas de desenvolvimento personalizadas. Você pode usar outras APIs do Salesforce para manipular subconjuntos de seus dados do Salesforce também. Por exemplo, a API REST do Analytics se concentra no Analytics. Mas essas quatro APIs aplicam-se amplamente ao espectro de dados principais do Salesforce.

REST API

A API REST é um serviço web simples e poderoso baseado em princípios RESTful. Expõe todo o tipo de funcionalidades do Salesforce por meio de recursos REST e métodos HTTP. Por exemplo, você pode criar, ler, atualizar e excluir (CRUD) registros, pesquisar ou consultar seus dados, obter metadados de objeto e acessar informações sobre limites em sua organização. A API REST aceita tanto XML quanto JSON.

Uma vez que a API REST tem uma estrutura de solicitações e respostas leve (além de ser fácil de usar), ela é excelente para escrever aplicativos móveis e aplicativos da web.

API SOAP

A API SOAP é um serviço web robusto e poderoso baseado no protocolo padrão do setor com o mesmo nome. Usa um arquivo WSDL (Web Services Description Language, Linguagem de Descrição de Serviços Web) para definir rigorosamente os parâmetros de acesso de dados por meio da API. A API SOAP aceita apenas XML. A maior parte da funcionalidade API SOAP está também disponível por meio da API REST. Depende apenas de qual padrão atende melhor as suas necessidades.

Uma vez que a API SOAP usa o arquivo WSDL como um contrato formal entre a API e o consumidor, ela é excelente para escrever integrações entre servidores.

API em massa

A API em massa é uma API RESTful especializada para carregar e consultar muitos dados de uma vez. Nesse contexto, “muitos” quer dizer 50.000 registros ou mais. A API em massa é assíncrona, ou seja, você pode enviar uma solicitação e voltar depois para ver os resultados. Essa abordagem é a preferida quando lidamos com uma grande quantidade de dados. Existem duas versões da API em massa (1.0 e 2.0). As duas versões lidam com grandes quantidades de dados, mas usamos a API em massa 2.0 neste módulo porque ela é mais fácil de usar.

A API em massa é ótima para realizar tarefas que envolvam muitos registros, tais como carregar dados para sua organização pela primeira vez.

API Pub/Sub

Use a API Pub/Sub para integrar sistemas externos com eventos em tempo real. Você pode assinar eventos em tempo real que são acionados quando alterações são feitas em seus dados, ou assinar eventos personalizados. As APIs usam um modelo publicação-assinatura, ou pub/sub, no qual os usuários podem assinar canais que transmitem alterações de dados ou notificações personalizadas.

O modelo pub/sub reduz o número de solicitações de API ao eliminar a necessidade de fazer solicitações de API frequentes para obter dados. A API Pub/Sub é ótima para escrever aplicativos que, de outra maneira, precisariam sondar alterações frequentemente.

Acesso e autenticação de API

Você não precisa de um mapa do tesouro para acessar as APIs do Salesforce. Tudo o que você precisa é de um Trailhead Playground ou de uma organização em uma das seguintes edições: Enterprise Edition, Unlimited Edition, Developer Edition, Performance Edition ou Professional Edition (com complemento). Certifique-se de que você tem a permissão “API ativada” e que está pronto para começar a integrar.

Todas as chamadas de API, exceto a chamada login() da API SOAP, precisam de autenticação. Você pode usar um dos fluxos OAuth suportados ou autenticar com uma ID de sessão recuperada da chamada login() da API SOAP. Consulte o guia do desenvolvedor para saber mais sobre a API que escolheu para começar.

Limites de API

O Salesforce limita o número de chamadas de API por organização para garantir a integridade da instância. Estes limites existem para prevenir que códigos maliciosos monopolizem recursos compartilhados no ambiente multilocatário. Eles não perturbam seu trabalho cotidiano. Ainda assim, é uma boa ideia se familiarizar com eles.

Existem três tipos de limites de API: limites de tempo, limites de solicitações concomitantes e total de alocações de solicitações. Os limites de tempo restringem o tempo durante o qual uma única chamada pode ser executada. Os limites concomitantes restringem o número de chamadas de longa duração que estão ocorrendo simultaneamente. Os limites concomitantes variam por tipo de organização. Por exemplo, as organizações de teste e as organizações de produção têm um limite diferente de solicitações concomitantes. Os limites totais restringem o número de chamadas feitas dentro de um período contínuo de 24 horas. Os limites totais variam dependendo da edição da organização e do tipo de licença, incluindo quaisquer licenças adicionais que você compra. Os limites totais são ainda sujeitos a mínimos e máximos com base na edição da organização, mas não vamos abordar isso agora. Se você quiser saber mais, confira o link Referência rápida de limites e alocações de desenvolvedor do Salesforce na seção Recursos.

Você tem várias maneiras de verificar suas chamadas de API restantes:

• A caixa de uso da API na página Visão geral do sistema. (Em Configuração, insira Visão geral do sistema na caixa Busca rápida e selecione Visão geral do sistema.)
• Informações retornadas no cabeçalho de resposta Sforce-Limit-Info para APIs REST.
• Informações retornadas no corpo da resposta (em <type>API REQUESTS</type>) para APIs SOAP.
• A chamada /limits na API REST.
• O limite de solicitações à API por direito baseado em uso mensal, que mostra a você as chamadas de API da sua organização no período de 30 dias.

Você pode ainda configurar notificações para quando sua organização excede um número de chamadas de API que você determina. Para fazer isso, em Configuração, insira Notificações de uso da API na caixa Busca rápida e selecione Notificações de uso da API.

Qual API eu uso?

Escolher a API certa para suas necessidades de integração é uma decisão importante. Aqui estão algumas informações sobre nossas APIs mais usadas, incluindo formatos de dados suportados, paradigmas de comunicação e casos de uso. Tenha esta seção como uma referência à qual você pode recorrer quando estiver considerando qual API usar.

Observe as quatro APIs de dados das quais já falamos. Vamos nos aprofundar em cada uma delas a seguir.

Quando usar a API REST

A API REST fornece uma interface de serviços Web poderosa, conveniente e simples baseada em REST para interação com o Salesforce. Suas vantagens incluem facilidade de integração e desenvolvimento, além de ser uma excelente escolha de tecnologia para ser usada com aplicativos móveis e projetos Web. Para alguns projetos, talvez seja melhor usar a API REST com outras APIs REST do Salesforce. Para criar uma interface de usuário que crie, leia, atualize e exclua registros, incluindo a criação de Interface de usuário para modos de exibição de lista, ações e listas de opções dependentes, use a API de interface de usuário. Para trabalhar com B2B Commerce, conteúdo gerenciado por CMS, sites do Experience Cloud e Chatter, use a API REST do Connect. Se você tem muitos registros para processar, considere usar a API em massa, que é baseada em princípios REST e otimizada para grandes conjuntos de dados.

Quando usar a API SOAP

A API SOAP fornece uma interface de serviços Web poderosa, conveniente e simples baseada em SOAP para interação com o Salesforce. Você pode usar a API SOAP para criar, recuperar, atualizar ou excluir registros. Você também pode usar a API SOAP para realizar pesquisas e muito mais. Use a API SOAP em qualquer linguagem que suporte serviços Web.

Por exemplo, você pode usar a API SOAP para integrar o Salesforce com o ERP e sistemas financeiros da sua organização. Você também pode fornecer vendas e informações de suporte em tempo real para portais de empresas e preencher sistemas comerciais importantes com informações de clientes.

Quando usar a API REST do Connect

A API REST do Connect fornece acesso programático ao B2B Commerce, conteúdo gerenciado por CMS, sites do Experience Cloud, arquivos, notificações, tópicos e muito mais. Use a API REST do Connect para construir uma interface de usuário para Chatter, tais como feeds, usuários e grupos, especialmente em aplicativos móveis.

Quando usar a API de interface de usuário

Crie uma interface de usuário do Salesforce para aplicativos móveis nativos e aplicativos da web personalizados usando a mesma API que a Salesforce usa para criar o para a Web e o Salesforce para Android, iOS e web móvel. Crie interfaces de usuário que permitem aos usuários trabalhar com registros, modos de exibição de lista, ações, favoritos e muito mais. Não só você receberá dados e metadados em uma mesma resposta, como também a resposta refletirá as alterações de metadados feitas na organização pelos administradores do Salesforce. Não se preocupe com layouts, listas de opções, segurança em nível de campo ou compartilhamento; concentre-se em criar um aplicativo que os usuários amam.

Quando usar a API REST do Analytics

Você pode acessar ativos do Analytics, como conjuntos de dados, lenses e painéis, programaticamente usando a API REST do Analytics. Envie consultas diretamente para a plataforma Analytics. Acesse conjuntos de dados que foram importados para a plataforma Analytics. Crie e recupere lenses. Acesse informações XMD. Recupere uma lista de versões de conjunto de dados. Crie e recupere aplicativos do Analytics. Crie, atualize e recupere painéis do Analytics. Recupere uma lista de dependências de um aplicativo. Determine quais recursos estão disponíveis para o usuário. Trabalhe com instantâneos. Manipule conjuntos de dados replicados.

Quando usar a API em massa

A API em massa é baseada em princípios REST e é otimizada para carregar ou excluir grandes conjuntos de dados. Você pode usá-la para consultar, queryAll, inserir, atualizar, inserir e atualizar ou excluir muitos registros de forma assíncrona enviando lotes. O Salesforce processa lotes em segundo plano.

Por outro lado, a API SOAP é otimizada para aplicativos cliente em tempo real que atualizam alguns registros por vez. Você pode usar a API SOAP para processar muitos registros mas, quando os conjuntos de dados contêm centenas de milhares de registros, ela é menos prática. A API em massa é desenvolvida para facilitar o processamento de dados de alguns milhares até milhões de registros.

A forma mais fácil de usar a API em massa é habilitá-la para processar registros no Data Loader usando arquivos CSV. Usar o Data Loader evita a necessidade de escrever seu próprio aplicativo cliente.

Quando usar a API de metadados

Use a API de metadados para recuperar, implantar, criar, atualizar ou excluir personalizações para sua organização. O uso mais comum é migrar alterações de uma sandbox ou organização de teste para seu ambiente de produção. A API de metadados é concebida para gerenciar personalizações e para criar ferramentas que possam gerenciar o modelo de metadados e não os dados em si.

A maneira mais fácil de acessar a funcionalidade na API de metadados é usar Extensões do Salesforce para Visual Studio Code ou a ferramenta de migração Ant. Ambas as ferramentas são criadas com base na API de metadados e usam as ferramentas padrão para simplificar o trabalho com a API de metadados. 

• Extensões do Salesforce para Visual Studio Code inclui ferramentas para desenvolvimento na Salesforce Platform, no editor leve e extensível VS Code. Essas ferramentas fornecem recursos para trabalhar com organizações de desenvolvimento (organizações temporárias, sandboxes e organizações DE), Apex, componentes do Aura e Visualforce.
• A Ferramenta de migração Ant é ideal se você usar um script ou a linha de comando para mover metadados entre um diretório local e uma organização do Salesforce.

Quando usar a API Pub/Sub

Você pode usar a API Pub/Sub para integrar sistemas externos com eventos em tempo real. Fluxos de dados são baseados em cargas úteis personalizadas através de eventos de plataforma ou alterações em registros do Salesforce através da Captura de dados de alteração. No Salesforce, você pode publicar e assinar eventos com acionadores do Apex, Process Builder e Flow Builder. 

A API Pub/Sub foi criada para integração de eventos bidirecionais de alta escala com o Salesforce. Use a API Pub/Sub para publicar e assinar mensagens de evento binárias com eficiência no formato Apache Avro. A API Pub/Sub é baseada em gRPC e HTTP/2 e usa um modelo baseado em demanda para que você possa controlar o fluxo de assinaturas. Com a API Pub/Sub, você pode usar uma das 11 linguagens de programação que são compatíveis com gRPC. 

Quando usar a API REST do Apex

Use a API REST do Apex quando você quiser expor suas classes e métodos do Apex de modo que os aplicativos externos possam acessar seu código por meio da arquitetura REST. A API REST do Apex suporta OAuth 2.0 e ID de sessão para autenticação.

Quando usar a API SOAP do Apex

Use a API SOAP do Apex quando você quiser expor métodos do Apex como APIs de serviço Web SOAP de modo que os aplicativos externos possam acessar seu código por meio de SOAP. A API SOAP do Apex suporta OAuth 2.0 e ID de sessão para autenticação.

Quando usar a API de ferramentas

Use a API de ferramentas para criar ferramentas ou aplicativos de desenvolvimento personalizados para aplicativos da Platform. Por exemplo, você pode usar a API de ferramentas para adicionar recursos e funcionalidades às suas ferramentas existentes na Platform e construir módulos dinâmicos em suas ferramentas de integração corporativas. Você também pode usar a API de ferramentas para criar ferramentas de desenvolvimento especializadas para um aplicativo ou serviço específico.

Os recursos de SOQL da API de ferramentas para muitos tipos de metadados permitem que você recupere pedaços menores de metadados. As recuperações de pedaços menores melhoram o desempenho, tornando a API de ferramentas uma boa opção para o desenvolvimento de aplicativos interativos. A API de ferramentas fornece interfaces SOAP e REST.

Quando usar a API GraphQL

Crie aplicativos com alta capacidade de resposta e expansão, retornando apenas os dados de que um cliente precisa, tudo em uma única solicitação. A API GraphQL supera os desafios impostos pelas APIs REST tradicionais fazendo a seleção de campos, a agregação de recursos e a introspecção no esquema. A seleção de campos reduz o tamanho da carga, devolvendo apenas os campos que foram incluídos na consulta. As agregações reduzem as idas e voltas entre o cliente e o servidor, retornando um conjunto de recursos relacionados em uma única resposta. A introspecção no esquema permite que o usuário veja os tipos, campos e objetos aos quais ele tem acesso.

Recursos

• Padrões e práticas de integração
• REST API Developer Guide
• SOAP API Developer Guide
• Bulk API 2.0 Developer Guide
• Documentação da API Pub/Sub
• Guia do desenvolvedor da API de metadados
• Guia do desenvolvedor da API de ferramentas
• Guia do desenvolvedor da API GraphQL
• Referência rápida de limites e alocações de desenvolvedor