Utilisation de l’API REST

Une ressource REST est une abstraction d’une information ou d’une action, par exemple un enregistrement de données unique, un groupe d’enregistrements ou une requête. Dans l’API REST, chaque ressource est identifiée par un URI (Uniform Resource Identifier) nommé, et accédée à l’aide de méthodes HTTP standard (HEAD, GET, POST, PATCH, DELETE). L’API REST est basée sur l’utilisation de ressources, de leurs URI et des liens qui les unissent.

Une requête REST est formée de quatre composants : un URI de ressource, une méthode HTTP, des en-têtes de requête et un corps de requête. Les en-têtes de requête spécifient les métadonnées de la requête. Le corps de requête spécifie les données de la requête, quand nécessaire. S’il n’existe aucune donnée à spécifier, le corps est omis dans la requête.

Vous êtes sur la page d'accueil de Workbench. Pour ce module, nous allons utiliser un seul outil Workbench, Explorateur REST.

Dans le menu supérieur, sélectionnez utilitaires | Explorateur REST.

Vous pouvez effectuer des appels vers l’API REST depuis l’explorateur REST, comme vous le feriez depuis n’importe quelle autre interface HTTP. Le texte de la zone de texte représente un URI de ressource. Pour simplifier, le domaine supérieur est omis dans l’URI affiché. Par exemple, l’URI complet de la ressource prérenseigné dans la zone de texte URI est https://foo.my.salesforce.com/services/data/v36.0.

Les options au-dessus de cette zone de texte représentent les méthodes HTTP standard. Pour effectuer un appel d’API, saisissez l’URI de la ressource, sélectionnez la méthode appropriée, ajoutez des en-têtes si nécessaire, puis cliquez sur Execute.

Essayons la ressource SObject Describe. Lorsqu’elle est combinée à la méthode GET, cette ressource renvoie les métadonnées d’un objet et de ses champs.

Nous allons essayer de décrire l’objet Account. Remplacez le texte existant dans la zone de texte URI par /services/data/vXX.0/sobjects/account/describe, où XX est mappé avec la version de l’API que vous utilisez.

Assurez-vous maintenant que la méthode GET est sélectionnée, puis cliquez sur Execute.

Du bon travail capitaine. Les métadonnées Account sont affichées sur l’écran. Le Workbench a mis en forme la réponse pour la rendre plus lisible. Pour afficher la réponse JSON brute, cliquez sur Show Raw Response.

Les métadonnées Account sont affichées en JSON sous quelques en-têtes de réponse HTTP. L’API REST prend en charge JSON et XML. Par conséquent, nous allons indiquer, dans l’en-tête de la requête, une réponse XML. En regard des méthodes HTTP, cliquez sur Headers. Dans la valeur de l’en-tête Accept, remplacez application/json par application/xml. Vos en-têtes de requête se présentent comme suit.

Cliquez sur Exécuter. La réponse XML brute est renvoyée. Hourra !

Cliquez sur Headers. Remplacez Accept: application/xml par Accept: application/json. Votre requête se présente comme suit.

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

Cliquez sur Exécuter. Une réponse semblable à la suivante s’affiche.

Si success: true, le compte a été créé avec l’ID renvoyé. Développez le dossier des erreurs pour les consulter.

{
  "ShippingCity" : "San Francisco"
}

Cliquez sur Exécuter.

Oulala ! Avez-vous reçu une réponse de type REQUIRED_FIELD_MISSING ? Développez le dossier REQUIRED_FIELD_MISSING, puis le dossier fields. Votre réponse développée se présente comme suit.

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

Cliquez sur Exécuter. Réussi !

Remplacez les données de la zone de texte de l’URI par la ligne suivante : /services/data/v XX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity=’San+Francisco’, où XX est mappé avec la version de l’API que vous utilisez.

Pour coder correctement l’URI dans la chaîne de la requête, nous avons remplacé les espaces par le caractère +. Pour plus d’informations sur le codage d’URL HTML, suivez les liens de la section Ressources. Assurez-vous que la méthode GET est sélectionnée, puis cliquez sur Execute.

Agrandissez le dossier records. Le dossier portant le nom du premier compte que nous avons créé, NewAccount1, est-il affiché ? Très bien ! Cliquez dessus. Cliquez ensuite sur le dossier attributes. L’URI de la ressource du compte renvoyé est affiché en regard de l’URL. Votre réponse se présente comme suit.

Lorsque vous écrivez une intégration, vous pouvez récupérer cet URI dans la réponse pour accéder à plus d’informations sur le compte.

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