Usar a API REST
Objetivos de aprendizagem
- 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
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.
- 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
- Faça login no Trailhead Playground e acesse o Workbench.
- Em Ambiente, selecione Produção.
- Em 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.

- /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.

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.

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.

Clique em Executar. A resposta XML bruta é retornada. Oba!
Criar uma conta
Clique em Cabeçalhos. Altere Accept: application/xml de volta para Accept: application/json. Sua solicitação tem essa aparência.

{ "Name" : "NewAccount1", "ShippingCity" : "San Francisco" }
Clique em Executar. Você verá uma resposta como a seguinte.

Se success: true, a conta foi criada com a ID retornada. Expanda a pasta de erros para verificar erros.
{ "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.

{ "Name" : "NewAccount2", "ShippingCity" : "New York" }
Clique em Executar. Sucesso!
Executar uma consulta
Substitua o texto na caixa de texto de URI pelo seguinte texto: /services/data/v XX.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.

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