Usar a API 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.

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.

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.

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!

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!

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.

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);
});

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