Usar a API REST

Objetivos de aprendizagem

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

Faça login no Workbench e navegue para o REST Explorer.
Use o recurso de descrição.
Criar uma conta usando a API REST.
Executar uma consulta usando a API REST.

Recursos e métodos REST

Terra à vista! Vemos a ilha de REST adiante, capitão! Antes de atracar e começar a usar a API, vamos falar sobre recursos e métodos REST

Um recurso REST é uma abstração de uma informação ou de uma ação, tal como um registro de dados individual, uma coleção de registros ou uma consulta. Cada recurso na API REST é identificado por um URI (Uniform Resource Identifier, Identificador de Recurso Uniforme) e é acessado usando métodos HTTP padrão (HEAD, GET, POST, PATCH, DELETE). A API REST é baseada no uso de recursos, seus URIs e os links entre eles.

Você usa um recurso para interagir com sua organização do Salesforce. É possível, por exemplo:

Obter informações resumidas sobre as versões de API disponíveis para você.
Obter informações detalhadas sobre um objeto Salesforce, como Conta, Usuário, ou sobre um objeto personalizado.
Fazer uma consulta ou pesquisa.
Atualizar ou excluir registros.

Uma solicitação REST consiste em quatro componentes: um URI de recurso, um método HTTP, cabeçalhos de solicitação e um corpo da solicitação. Cabeçalhos de solicitação especificam metadados para a solicitação. O corpo da solicitação especifica dados para a solicitação, quando necessário. Caso não haja dados para especificar, o corpo é omitido da solicitação.

Descrever o objeto de conta

Chegou a hora de colocar a mão na massa. Vamos usar o Workbench para fazer algumas chamadas de API. O Workbench é um conjunto de ferramentas para interação com sua organização do Salesforce por meio da API. Uma vez que você pode fazer solicitações REST a partir de qualquer remetente de HTTP, há muitas outras ferramentas disponíveis para você usar (por exemplo, cURL ou Postman). No entanto, visto que o Workbench fornece uma estrutura amigável especificamente para APIs do Salesforce, é a maneira perfeita de começar antes de você estar pronto para escrever uma integração completa.

A primeira etapa é fazer login no Workbench.

Faça login no Trailhead Playground e acesse o Workbench.
Em Ambiente, selecione Produção.
Para a versão da API, selecione o número mais alto disponível.
Certifique-se de marcar a opção Concordo com os termos de serviço.
Clique em Login com o Salesforce.

Você chegou à página inicial do Workbench. Para este módulo, usamos apenas uma das muitas ferramentas do Workbench, o REST Explorer.

No menu superior, selecione utilitários | REST Explorer.

Você pode fazer chamadas à API REST a partir do REST Explorer do mesmo modo que faria de qualquer outra interface HTTP. O texto na caixa de texto representa um URI de recurso. Por conveniência, o domínio de nível superior é omitido do URI exibido. Por exemplo, o URI completo do recurso que é pré-preenchido na caixa de texto de URI é https://foo.my.salesforce.com/services/data/v36.0.

Os botões de opção acima do URI representam os métodos HTTP padrão. Para fazer uma chamada de API, insira o URI do recurso, selecione o método apropriado e os cabeçalhos necessários e clique em Executar

Vamos experimentar o recurso SObject Describe. Este recurso, quando combinado com o método GET, retorna metadados sobre um objeto e seus campos.

Vamos tentar descrever o objeto de conta. Na caixa de texto de URI, substitua o texto existente por /services/data/vXX.0/sobjects/account/describe, em que XX mapeia para a versão da API que você está usando.

Vamos dedicar um tempo para decompor o URI deste recurso.

/services/data – Especifica que estamos fazendo uma solicitação à API REST
/v36.0 – Número de versão da API
/sobjects – Especifica que estamos acessando um recurso no agrupamento sObject
/account – sObject sendo acionado; neste caso, conta
/describe – Ação; neste caso, uma solicitação de descrição

Verifique agora se o método GET está selecionado e clique em Executar.

Resposta após descrevermos o objeto de conta

Bom trabalho! Os metadados da conta aparecem na tela. E o Workbench formatou muito bem a resposta. Para ver a resposta JSON bruta, clique em Exibir resposta bruta.

Resposta JSON após descrevermos o objeto de conta

Os metadados da conta são exibidos em formato JSON abaixo de alguns cabeçalhos de resposta HTTP. Uma vez que a API REST aceita tanto JSON quanto XML, vamos alterar o cabeçalho de solicitação para especificar uma resposta XML. Perto dos métodos de HTTP, clique em Cabeçalhos. Para o valor de cabeçalho Accept, substitua application/json por application/xml. Seu cabeçalho de solicitação tem essa aparência.

Cabeçalho de solicitação especificando XML

Clique em Executar. A resposta XML bruta é retornada. Oba!

Criar uma conta

Vamos agora criar uma conta usando o recurso SObject e o método POST. Na caixa de texto de URI, substitua o texto existente por /services/data/vXX.0/sobjects/account, em que XX mapeia para a versão da API que você está usando. Selecione POST. Aparece uma área de texto Corpo da solicitação, que é onde especificamos os valores de campo para nossa nova conta. Primeiro, vamos alterar o cabeçalho Accept de volta para JSON.

Clique em Cabeçalhos. Altere Accept: application/xml de volta para Accept: application/json. Sua solicitação tem essa aparência.

Digite o seguinte texto no corpo da solicitação.

{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

Clique em Executar. Você verá uma resposta como a seguinte.

Resposta de criação de conta bem-sucedida na API REST

Se success: true, a conta foi criada com a ID retornada. Expanda a pasta de erros para verificar erros.

Para animar, vamos criar uma segunda conta sem especificar um nome de conta. Substitua o texto no corpo da solicitação pelo seguinte texto.

{
  "ShippingCity" : "San Francisco"
}

Clique em Executar.

Oh, não! Você recebeu uma resposta REQUIRED_FIELD_MISSING? Expanda a pasta REQUIRED_FIELD_MISSING e, então, expanda a pasta fields. Sua resposta expandida tem essa aparência.

Recebemos um erro quando não fornecemos um nome de conta

Uma vez que Name é um campo obrigatório para criar uma conta, o servidor não processou a solicitação e recebemos um erro. Felizmente, todas as informações que precisamos para corrigir a solicitação estão na resposta de erro. Vamos especificar o nome NewAccount2 e alterar a cidade de envio no corpo da solicitação. Substitua o texto no corpo da solicitação pelo seguinte texto.

{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

Clique em Executar. Sucesso!

Executar uma consulta

Vamos agora imaginar que você ou outro usuário criou centenas de contas. Você quer encontrar os nomes de todas as contas em que a cidade de envio é São Francisco. Você pode usar o recurso Consulta para executar uma consulta SOQL e concentrar-se nos registros exatos desejados, assim como em um mapa do tesouro personalizado.

Substitua o texto na caixa de texto de URI pelo seguinte texto: /services/data/vXX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity='San+Francisco', em que XX mapeia para a versão de API que você está usando.

Substituímos os espaços pelo caractere + na sequência de caracteres de consulta para codificar corretamente o URI. Você pode ler sobre a codificação de URL HTML no link na seção Recursos. Verifique se o método GET está selecionado e clique em Executar.

Expanda a pasta records. Você vê uma pasta com o nome da primeira conta que criamos, NewAccount1? Ótimo. Clique nela. Agora clique na pasta attributes. Ao lado do URL está o URI do recurso da conta que foi retornada. Sua resposta tem mais ou menos essa aparência.

A resposta da consulta retorna um registro de conta

Quando você escreve uma integração, você pode pegar esse URI da resposta para acessar mais detalhes sobre essa conta.

Amostras Node.js e Ruby

Agora você já tem um gostinho do que é possível fazer com a API REST. É claro que quando você mudar do Workbench para escrita de código, você estará interagindo com a API REST usando sua linguagem de programação preferida. Felizmente, desenvolvedores especialistas em Salesforce escreveram wrappers para várias linguagens que simplificam o processo de consumo da API REST. Aqui estão duas consultas de amostra escritas em Node.js e Ruby que usam wrappers Nforce e Restforce, respectivamente.

Amostra Node.js usando Nforce

var nforce = require('nforce');

// create the connection with the Salesforce connected app
var org = nforce.createConnection({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.CALLBACK_URL,
  mode: 'single'
});

// authenticate and return OAuth token
org.authenticate({
  username: process.env.USERNAME,
  password: process.env.PASSWORD+process.env.SECURITY_TOKEN
}, function(err, resp){
  if (!err) {
    console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token);
    // execute the query
    org.query({ query: 'select id, name from account limit 5' }, function(err, resp){
      if(!err && resp.records) {
        // output the account names
        for (i=0; i<resp.records.length;i++) {
          console.log(resp.records[i].get('name'));
        }
      }
    });
  }
  if (err) console.log(err);
});

Amostra Ruby usando Restforce

require 'restforce'

// create the connection with the Salesforce connected app
client = Restforce.new :username => ENV['USERNAME'],
  :password       => ENV['PASSWORD'],
  :security_token => ENV['SECURITY_TOKEN'],
  :client_id      => ENV['CLIENT_ID'],
  :client_secret  => ENV['CLIENT_SECRET']

// execute the query
accounts = client.query("select id, name from account limit 5")

// output the account names
accounts.each do |account|
  p account.Name
end

Recursos

REST API Developer Guide

Getting Started with Salesforce REST in Java

HTML URL Encoding Reference

Workbench

Nota

Lembre-se: este módulo é destinado ao Salesforce Classic. Quando você iniciar sua organização prática, mude para o Salesforce Classic para concluir este desafio.

Tópicos