How to use Salesforce REST API with your JavaServer Pages

Abstract: This tutorial gives an example of a JSP and how to integrate it with the Salesforce REST API. We will walk through the step­by­step process of creating an external client to manage your data with Force.com,while using HTTP(S) and JSON.

In this example, I am using Mac OS X 10.9.2 with Apache Tomcat 7 server and Java 1.7. Eclipse Java EE edition is the IDE used for development and testing. The instructions given in this tutorial should work with minor modifications for other platforms as well.

If you want to access the entire sample code from this tutorial, you can access it here: github.com/seethaa/force_rest_example

All code is updated to work with the httpclient 4.3 libraries.

What Is REST?

REST stands for Representational State Transfer, and is a stateless client­server communications protocol over HTTP.

Why and When To Use A REST API in Java for Your JSP

A REST API is well suited for browser applications which require a lot of interaction, and uses synchronous communication to transfer data. The Salesforce REST API provides a programming interface for simple web services to interact with Force.com, and supports both XML and JSON formats. The Salesforce REST API works well for mobile applications or dynamic websites to retrieve or update records quickly on your web server. While bulk record retrieval should be reserved for the BulkAPI, this lightweight REST API can be used for common server pages which involve quick updates and frequent user interactions, for example updating a single user record.

Setting Up Your Development Account and Prerequisites

You will need the following:

1. Go to https://developer.salesforce.com/signup and register for your Free DE account. For the purposes of this example, I recommend sign up for a Developer Edition even if you already have an account. This ensures you get a clean environment with the latest features enabled.
2. Java application Server. I created mine using Apache Tomcat 7 on Mac OS X and Eclipse as the IDE. There is also a free Eclipse plugin at http://developer.salesforce.com/page/Force.com_IDE but the original Eclipse setup was used in this tutorial.
3. Configure SSL on your Tomcat server using http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html. If you are developing in Eclipse, make sure to add the Connector piece in server.xml file in your Eclipse environment, e.g.:

   1	<Connector SSLEnabled="true" clientAuth="false" keystoreFile="/Users/seetha/.keystore" keystorePass="password" maxThreads="200" port="8443" protocol="HTTP/1.1" scheme="https" secure="true" sslProtocol="TLS"/>

4. Add the required jar files to WebContent/WEB­INF/lib. You will need commons-­codec-­1.6.jar, httpclient­4.3.3.jar, httpcore-­4.3.2.jar, commons-­logging­-1.1.3.jar, and java-­json.jar. For Eclipse, I also had to make sure that all jars were added to the build path (Right click Project → Build Path → Configure build path →  Select Libraries tab → Click Add Jars → Select the Jar files from the WEB­INF/lib folder.

Create a Connected App

1. Back in your Force.com DE, create a new Connected App through the console. Click on Setup → Build → Create → Apps. Scroll down to the Connected Apps section and click on the New button.
   • Ensure that the callback URL is http://localhost:8080/<your_app_context_path>/oauth/_callback

     (You can find the app context path by going back to Eclipse: Right clicking on Project → Properties → Web Project Settings → Context root)

   • Check “Enable OAuth Settings” checkbox
   • The required OAuth scopes for this tutorial (see Figure 1) are “Access and manage your data (api)” and “Provide access to your data via the Web (web)”, but these scopes should be changed as per your requirement.
   • Save

     

2. Copy the ClientID and Client Secret (see Figure 2), because both of these will be used in the next step.
    
   

   

   Authentication

   There are three files that need to be imported into your JSP project, given below:

   index.html

   01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16

   <!DOCTYPE html PUBLIC "­//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http­equiv="Content­Type" content="text/html; charset=UTF­8"> <title>REST/OAuth Example</title> </head> <body>     <script type="text/javascript"  language="javascript">     if (location.protocol != "https:") {         document.write("OAuth  will not work correctly from plain http. "+ "Please use an https URL.");     } else {         document.write("<a href=\"oauth\">Run Connected App demo via REST/OAuth.</a>");     }     </script> </body> </html>

   OAuthConnectedApp.java

   001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151

   import java.io.IOException; import java.io.InputStream; import java.io.UnsupportedEncodingException; import java.net.URLEncoder; import java.util.ArrayList; import java.util.List;   import javax.servlet.ServletException; import javax.servlet.annotation.WebInitParam; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse;   import org.apache.http.Consts; import org.apache.http.HttpEntity; import org.apache.http.NameValuePair; import org.apache.http.client.entity.UrlEncodedFormEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.message.BasicNameValuePair;   import org.json.JSONException; import org.json.JSONObject; import org.json.JSONTokener;   @WebServlet(name  = "oauth", urlPatterns = { "/oauth/*", "/oauth" }, initParams = { // clientId is 'Consumer Key' in the Remote Access UI //**Update with your own Client ID @WebInitParam(name  = "clientId", value = "3MVG9JZ_r.QzrS7jzujCYrebr8kajDEcjXQLXnV9nGU6PaxOjuOi_n8EcUf0Ix9qqk1lYCa4_Jaq7mpqxi2YT"), // clientSecret is 'Consumer Secret' in the Remote Access UI //**Update with your own Client Secret @WebInitParam(name  = "clientSecret", value = "2307033558641049067"), // This must be identical to 'Callback URL' in the Remote Access UI //**Update with your own URI @WebInitParam(name  = "redirectUri", value = "http://localhost:8080/force_rest_example/oauth/_callback"), @WebInitParam(name  = "environment", value = "https://login.salesforce.com"), })   /** * Servlet parameters * @author  seetha * */ public class OAuthConnectedApp  extends HttpServlet {       private static final long serialVersionUID = 1L;       private static final String ACCESS_TOKEN = "ACCESS_TOKEN";     private static final String INSTANCE_URL = "INSTANCE_URL";       private String clientId = null;     private String clientSecret = null;     private String redirectUri = null;     private String environment = null;     private String authUrl = null;     private String tokenUrl = null;           public void init() throws ServletException {                   clientId = this.getInitParameter("clientId");         clientSecret = this.getInitParameter("clientSecret");         redirectUri = this.getInitParameter("redirectUri");         environment = this.getInitParameter("environment");           try {               authUrl = environment             + "/services/oauth2/authorize?response_type=code&client_id="             + clientId + "&redirect_uri="             + URLEncoder.encode(redirectUri, "UTF­8");         }         catch (UnsupportedEncodingException e) {             throw new ServletException(e);         }           tokenUrl = environment + "/services/oauth2/token";     }       protected void doGet(HttpServletRequest request, HttpServletResponse  response) throws ServletException, IOException {               String accessToken = (String) request.getSession().getAttribute(ACCESS_TOKEN);           //System.out.println("calling doget");         if (accessToken == null) {             String instanceUrl = null;               if (request.getRequestURI().endsWith("oauth")) {                 // we need to send the user to authorize                 response.sendRedirect(authUrl);                 return;             }             else {                 System.out.println("Auth successful ­ got callback");                 String code = request.getParameter("code");                   // Create an instance of HttpClient.                 CloseableHttpClient  httpclient = HttpClients.createDefault();                   try{                     // Create an instance of HttpPost.                     HttpPost httpost = new HttpPost(tokenUrl);                       // Adding all form parameters in a List of type NameValuePair                     List<NameValuePair>  nvps = new ArrayList<NameValuePair>();                     nvps.add(new BasicNameValuePair("code", code));                     nvps.add(new BasicNameValuePair("grant_type","authorization_code"));                     nvps.add(new BasicNameValuePair("client_id", clientId));                     nvps.add(new BasicNameValuePair("client_secret", clientSecret));                     nvps.add(new BasicNameValuePair("redirect_uri", redirectUri));                       httpost.setEntity(new  UrlEncodedFormEntity(nvps, Consts.UTF_8));                                           // Execute the request.                     CloseableHttpResponse closeableresponse=httpclient.execute(httpost);                     System.out.println("Response Statusline:"+closeableresponse.getStatusLine());                       try {                         // Do the needful with entity.                         HttpEntity entity = closeableresponse.getEntity();                         InputStream rstream = entity.getContent();                         JSONObject authResponse = new JSONObject(new JSONTokener(rstream));                           accessToken = authResponse.getString("access_token");                         instanceUrl = authResponse.getString("instance_url");                       } catch (JSONException e) {                         // TODO Auto­generated catch block e.printStackTrace();                         e.printStackTrace();                     } finally {                         // Closing the response                         closeableresponse.close();                     }                 } finally {                     httpclient.close();                 }               }               // Set a session attribute so that other servlets can get the access token             request.getSession().setAttribute(ACCESS_TOKEN, accessToken);               // We also get the instance URL from the OAuth response, so set it in the session too             request.getSession().setAttribute(INSTANCE_URL, instanceUrl);         }           response.sendRedirect(request.getContextPath() + "/ConnectedAppREST");     }       }

   ConnectedAppREST.java

   001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314

   import java.io.IOException; import java.io.InputStream; import java.io.PrintWriter; import java.net.URISyntaxException; import java.util.Iterator;   import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse;   import org.apache.http.HttpEntity; import org.apache.http.HttpStatus; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpDelete; import org.apache.http.client.methods.HttpGet; import org.apache.http.client.methods.HttpPost; import org.apache.http.client.utils.URIBuilder; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients;   import org.json.JSONArray; import org.json.JSONException; import org.json.JSONObject; import org.json.JSONTokener;   @WebServlet(urlPatterns = { "/ConnectedAppREST"  }) /** * Demo for Connect App/REST API * @author  seetha * */ public class ConnectedAppREST  extends HttpServlet {       private static final long serialVersionUID = 1L;     private static final String ACCESS_TOKEN = "ACCESS_TOKEN";     private static final String INSTANCE_URL = "INSTANCE_URL";           private void showAccounts(String  instanceUrl, String accessToken,         PrintWriter writer) throws ServletException, IOException {                   CloseableHttpClient  httpclient = HttpClients.createDefault();           HttpGet httpGet = new HttpGet();           //add key and value         httpGet.addHeader("Authorization", "OAuth " + accessToken);           try {                       URIBuilder builder = new URIBuilder(instanceUrl+ "/services/data/v30.0/query");             builder.setParameter("q", "SELECT Name, Id from Account LIMIT 100");               httpGet.setURI(builder.build());               CloseableHttpResponse  closeableresponse = httpclient.execute(httpGet);             System.out.println("Response Status line :" + closeableresponse.getStatusLine());                           if (closeableresponse.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {                 // Now lets use the standard java json classes to work with the results                 try {                     // Do the needful with entity.                     HttpEntity entity = closeableresponse.getEntity();                     InputStream rstream = entity.getContent();                     JSONObject authResponse = new JSONObject(new JSONTokener(rstream));                       System.out.println("Query response: " + authResponse.toString(2));                       writer.write(authResponse.getInt("totalSize") + " record(s) returned\n\n");                       JSONArray results = authResponse.getJSONArray("records");                                           for (int i = 0; i < results.length(); i++) {                     writer.write(results.getJSONObject(i).getString("Id")                         + ", "                         + results.getJSONObject(i).getString("Name")                         + "\n");                     }                                           writer.write("\n");                 }                 catch (JSONException e) {                     e.printStackTrace();                     throw new ServletException(e);                 }             }                       } catch (URISyntaxException  e1) {             // TODO Auto­generated catch block             e1.printStackTrace();         } finally {             httpclient.close();         }     }           private String createAccount(String  name, String instanceUrl,         String accessToken, PrintWriter writer) throws ServletException, IOException {                   String accountId = null;         CloseableHttpClient  httpclient = HttpClients.createDefault();         JSONObject account = new JSONObject();                   try {             account.put("Name",  name);         }         catch (JSONException e) {             e.printStackTrace();             throw new ServletException(e);         }                   HttpPost httpost = new HttpPost(instanceUrl+  "/services/data/v30.0/sobjects/Account/");           httpost.addHeader("Authorization", "OAuth " + accessToken);           StringEntity messageEntity = new StringEntity( account.toString(), ContentType.create("application/json"));           httpost.setEntity(messageEntity);           // Execute the request.         CloseableHttpResponse  closeableresponse = httpclient.execute(httpost);         System.out.println("Response Status line :" + closeableresponse.getStatusLine());                   try {                       writer.write("HTTP status " + closeableresponse.getStatusLine().getStatusCode() + " creating account\n\n");               if (closeableresponse.getStatusLine().getStatusCode()  == HttpStatus.SC_CREATED) {                               try {                                       // Do the needful with entity.                     HttpEntity entity = closeableresponse.getEntity();                     InputStream rstream = entity.getContent();                     JSONObject authResponse = new JSONObject(new JSONTokener(rstream));                                           System.out.println("Create response: " + authResponse.toString(2));                       if (authResponse.getBoolean("success")) {                         accountId = authResponse.getString("id");                         writer.write("New record id " + accountId + "\n\n");                     }                                       } catch (JSONException e) {                     e.printStackTrace();                     // throw new ServletException(e);                 }             }         }         finally {             httpclient.close();         }           return accountId;     }           private void showAccount(String  accountId, String instanceUrl,         String accessToken, PrintWriter writer) throws ServletException, IOException {           CloseableHttpClient  httpclient = HttpClients.createDefault();         HttpGet httpGet = new HttpGet();               //add key and value         httpGet.addHeader("Authorization", "OAuth " + accessToken);                   try {                       URIBuilder builder = new URIBuilder(instanceUrl + "/services/data/v30.0/sobjects/Account/" + accountId);               httpGet.setURI(builder.build());               //httpclient.execute(httpGet);               CloseableHttpResponse  closeableresponse = httpclient.execute(httpGet);             System.out.println("Response Status line :" + closeableresponse.getStatusLine());                           if (closeableresponse.getStatusLine().getStatusCode()  == HttpStatus.SC_OK) {                   try {                                       // Do the needful with entity.                     HttpEntity entity = closeableresponse.getEntity();                     InputStream rstream = entity.getContent();                     JSONObject authResponse = new JSONObject(new JSONTokener(rstream));                                           System.out.println("Query response: " + authResponse.toString(2));                     writer.write("Account  content\n\n");                                           Iterator iterator = authResponse.keys();                       while (iterator.hasNext()) {                         String key = (String) iterator.next();                           Object obj = authResponse.get(key);                         String value = null;                                           if (obj instanceof String) {                             value = (String) obj;                         }                           writer.write(key + ":" + (value != null ? value : "") + "\n");                     }                       writer.write("\n");                                       } catch (JSONException e) {                     e.printStackTrace();                     throw new ServletException(e);                 }             }                       }         catch (URISyntaxException  e1) {             // TODO Auto­generated catch block             e1.printStackTrace();         } finally {             httpclient.close();         }     }           private void updateAccount(String  accountId, String newName, String city, String instanceUrl, String accessToken, PrintWriter writer) throws ServletException, IOException {                   CloseableHttpClient  httpclient = HttpClients.createDefault();           JSONObject update = new JSONObject();                   try {             update.put("Name", newName);             update.put("BillingCity", city);         }         catch (JSONException e) {             e.printStackTrace();             throw new ServletException(e);         }                   HttpPost httpost = new HttpPost(instanceUrl + "/services/data/v30.0/sobjects/Account/" +accountId+"?_HttpMethod=PATCH");         httpost.addHeader("Authorization", "OAuth " + accessToken);         StringEntity messageEntity = new StringEntity( update.toString(), ContentType.create("application/json"));           httpost.setEntity(messageEntity);                   // Execute the request.         CloseableHttpResponse  closeableresponse = httpclient.execute(httpost); System.out.println("Response Status line :" + closeableresponse.getStatusLine());                   try {             writer.write("HTTP status " + closeableresponse.getStatusLine().getStatusCode() + " updating account " + accountId + "\n\n");         } finally {             httpclient.close();         }     }           private void deleteAccount(String  accountId, String instanceUrl, String accessToken, PrintWriter writer) throws IOException {           CloseableHttpClient  httpclient = HttpClients.createDefault();           HttpDelete delete = new HttpDelete(instanceUrl + "/services/data/v30.0/sobjects/Account/" + accountId);           delete.setHeader("Authorization", "OAuth " + accessToken);           // Execute the request.         CloseableHttpResponse  closeableresponse = httpclient.execute(delete);         System.out.println("Response Status line :" + closeableresponse.getStatusLine());                   try {             writer.write("HTTP status " + closeableresponse.getStatusLine().getStatusCode() + " deleting account " + accountId + "\n\n");         } finally {             delete.releaseConnection();         }     }           /**     * @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse     *      response)     */     @Override     protected void doGet(HttpServletRequest request, HttpServletResponse  response) throws ServletException, IOException {               PrintWriter writer = response.getWriter();           String accessToken = (String) request.getSession().getAttribute( ACCESS_TOKEN);           String instanceUrl = (String) request.getSession().getAttribute( INSTANCE_URL);           if (accessToken == null) {             writer.write("Error ­ no access token");             return;         }                   writer.write("We have an access token: " + accessToken + "\n" + "Using instance " + instanceUrl + "\n\n");           showAccounts(instanceUrl, accessToken, writer);           String accountId = createAccount("My New Org", instanceUrl, accessToken, writer);           if (accountId == null) {             System.out.println("Account ID null");         }           showAccount(accountId,  instanceUrl, accessToken, writer);         showAccounts(instanceUrl, accessToken, writer);                   updateAccount(accountId, "My New Org, Inc", "San Francisco", instanceUrl, accessToken, writer);           showAccount(accountId,  instanceUrl, accessToken, writer);           deleteAccount(accountId, instanceUrl, accessToken, writer);           showAccounts(instanceUrl, accessToken, writer);               }       }

3. Change OAuthConnectedApp.java to replace Client ID, Client Secret, and Callback URI fields based on the Connected App configuration.
4. Start Tomcat server in Eclipse (see Figure 3) or externally, and navigate to https://localhost:8443/<your_app_context_path>/

   

   
    
   

   

5. Clicking on the link above (see Figure 4) will not work unless it is through HTTPS, and SSL must be configured as endpoint for Tomcat.

   If all configurations were done properly, you should see a salesforce.com login screen (see Figure 5). Go ahead and login with your salesforce.com credentials to authorize your web application to access resources.

   

6. Logging in will allow the ConnectedAppREST demo to execute methods to create, show, update, and delete records (see Figure 6).

   

*Tips & Warnings

1. Make sure you have a Developer Edition (DE) account, because there are slight differences between Professional, Enterprise, Developer, etc. The Developer edition is free and does not expire (unless unused after a year).
2. The callback URL in the OAuthConnectedApp.java must be same as the URL added to the connected app.
3. If you get HTTP 403 error, it means the resource you are requesting is “Forbidden” from being accessed. Check that the username/account you are accessing with has the appropriate permissions.
4. Make sure index.html is directly under the WebContent directory.

Resources

For a comprehensive set or resources, check out: http://developer.salesforce.com/en/mobile/resources

References

1. Force.com REST API Developer’s Guide (PDF)
2. Using the Force.com REST API

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.