Remember I mentioned that using a wrapper class facilitates rapid development? Here's how it works. We've already established a constructor that generates an instance of our wrapper class and returns it to us. If we go one step further, we'll be able to accept JSON representations of our wrapper class for input! What's that step? It is a no operation constructor like this:

//no operation constructor for general deserialization from JSON
public OppApiWrapper(){} 

With this no operation constructor in place, Apex will take our incoming JSON payload and attempt to deserialize it to an instance of our wrapper class. This means that our nested objects can be created with a method like this:

@HttpPost
  global static OppApiWrapper CreateTree(OppApiWrapper incoming) {
  if(incoming == null && incoming.opp != null) {
    throw new OppApiException('Incoming JSON paylaod failed to
      deserialize to an object with an Opportunity key');
  }
  //The point of this is to create object trees in a 
  //transaction, so lets set a savepoint.
  SavePoint tx = Database.setSavepoint();

  //Try inserting just the opportunity. We'll need it's ID 
  //to properly insert the child objects
  try{
    insert incoming.opp;
  } catch (DMLException dmle){
    //if we cannot insert the opp, abort the transaction 
    //and throw exception.
    Database.rollback(tx);
    throw new OppApiException(dmle);
  }
  //Now that we have the opportunities ID we can assign it 
  //to the child objects
  for(OpportunityLineItem oli: incoming.oppLineItems){
    oli.OpportunityId = incoming.opp.id;
  } 
  for(Order o: incoming.oppOrders){
    o.OpportunityId = o.id;
  }
  //now lets try inserting our child objects. 
  //we can do these together.
  //if either fails, abort the transaction and throw an exception.
  try{
    insert incoming.oppLineItems;
    insert incoming.OppOrders;
  } catch (DMLException dmle) {
    Database.rollback(tx);
    throw new OppApiException(dmle);
  }
  //Everything worked great! now lets return a new wrapper 
  //object from our new opportunity
  return new OppApiWrapper(incoming.opp.id);
}

Letting Apex deserialize our incoming JSON into Opportunity and lists of OpportunityLineItems and Quotes allows us to focus on the mechanics and ordering the object's creation. Notice how this method is annotated with @HttpPost. This is the convention for RESTful API creation calls. If we end up throwing an exception, the response back to the client will contain our error message and be marked with an HTTP failure status.

/services/apexrest/OpportunityApi/006A0000009Yoed.

@HttpPatch
global static OppApiWrapper remapChildren(OppApiWrapper incoming){
  try {
    upsert incoming.opp;
    upsert incoming.oppLineItems;
    upsert incoming.oppOrders;
  } catch(DMLException dmle){
    throw new OppApiException(dmle);
  }
  return new OppApiWrapper(incoming.opp.id);
}

Deleting data is, perhaps, too easy with custom rest APIs. It's a simple delete DML call. However, knowing what you have to delete and how you want to pass that data in is a bit more complex. In our case, we've created this RESTful API to function with, and on, an entire Object tree. Opportunities are the parent records for both orders and opportunity line items. As a result, the rest call we create only needs to delete the parent opportunity; the system will delete the dependent child objects for us. This isn't always the case, however, and if you needed to delete a tree of records associated through a lookup relationship, you'll need to identify those objects and delete them yourself.

Once you've determined what to delete, you'll need to set up your @httpDelete method to pull the record ID from the URI property of RestContext (or use a common helper method to do it for you). This is because the REST convention dictates that a delete request should be made to a specific record URI, and the Salesforce @httpDelete methods cannot accept parameters. Thus, we'll need to specify the record's ID in the URI as follows:

/services/apexrest/OpportunityApi/006A0000009Yoed

Thus, our delete method looks like this:

@HttpDelete
global static Boolean deleteObjectTree(){
  Boolean result = false;
  id UriID = OpportunityApi.getRequestUriId(RestContext.request);
    try{
        Opportunity toDelete = [SELECT id FROM Opportunity WHERE id = :UriID];
        delete toDelete;
        result = true;
    } catch (DMLException dmle){
        throw new OppApiException(dmle);
    }
  return result;
}

This style of delete method adheres to conventions, but suffers from the same problems the standard sObject API has; you can only delete one record at a time. Throughout this chapter, I've talked about RESTful conventions, not REST rules. While the conventions are there for good reasons, sometimes you just need a bulk-delete method. In these situations, it's useful to remember that we can override these conventions and build our API method with a different action verb. Instead of calling DELETE, for instance, we can call PUT. Since you're the author of these API methods, you can ignore convention and code a PUT method that deletes the records specified in the JSON body. In fact, you can use @HttpPut, @HttpPatch, or @HttpPost to do this. Although you can, you should only overload the PUT, PATCH, and POST methods for destructive changes when you cannot otherwise help it. Let's take a look at what such a bulk-delete method might look like:

@HttpPut
  global static Boolean bulkDelete(List<String> ids){
  Id first = (id)ids[0];
  Schema.SObjectType sobjectType = first.getSObjectType();
  String sobjectName = sobjectType.getDescribe().getName();
  List<sObject> toDelete = Database.query('Select Id From ' + sobjectName + ' Where Id IN :Ids');
    
  boolean SuccessfullyDeleted = false;
  try{
  delete toDelete;
  SuccessfullyDeleted = true;
} catch (DMLException dmle){
  throw new OppApiException(dmle);
}
  return SuccessfullyDeleted;
}

Here, our method is annotated @HttpPut, and we're sending JSON data containing which ID to delete. Our method has to pull sObjects from these IDs in order to delete them, so the majority of our method here isn't in actually deleting, but in finding the records to delete. Note the meta programming around the sObject name. Because we're pulling the sObject off of the first ID, we can technically use this method to delete any kind of object, but we need all the IDs to be of one object type. You can code around this, allowing for a bulk-multi-object delete, but I'll leave that exercise up to you. I want to stress that while this is an option, and one I've used successfully in the past, you should only break the convention if you absolutely have to.

Making a callout from Apex involves three different objects: A request object, an Http object, and the response object. We'll need to make a request object, and in return, we'll get a response object from the http object when we send that request. When we create the request, we have to set the endpoint, the action, and any required headers. Additionally, we can send a JSON or XML payload body if required. Let's construct a simple get request to Google to demonstrate the mechanics:

public string getRequest(){
  HttpRequest req = new HttpRequest();
  //Set HTTPRequest Method
  req.setMethod('GET');
  req.setEndpoint('https://www.google.com?q=codefriar.com');
  //Create the http object
  Http http = new Http();

  try {
    //This executes the rest request
 HTTPResponse res = http.send(req);
 //Dump result to logs for debugging
 System.debug(res.toString());
  } catch(System.CalloutException e) {
 //If it fails, handle it responsibly
  }
}

This may seem cumbersome and verbose at first glance, but in reality, it's quite elegant, if very low level. To make this easier on ourselves, we need to create some intelligent abstractions on these calls. Ultimately, it'd be pretty handy to have .post(), .get(), .patch(), and .delete() methods at our disposal. I tend to refer to libraries like this as RestClients. Building such a RestClient would allow us to quickly and easily make REST requests regardless of the API we were integrating with. If we build it with object-oriented inheritance in mind, we'll have a library we can extend into specific classes for individual APIs. In the end, our call out REST architecture would look like this:

To build this, let's think through what properties, constructors, and methods a RestClient will need. Initially, we'll need properties for endpoint, body, method, and headers. These properties work together to provide all that is needed to make a REST request. We'll need a request generator method and execution and response handling methods. Since we'll want to be able to extend this, our class should also be a virtual class. Here's an example of what a basic RestClient would look like:

public with sharing virtual class RestClient {
 Public class RestClientException extends Exception {}

 Public Map<String, String> headers = new Map<String, String>();
 Public String endpoint = '';
 Public String method = '';
 Public String body = '';
 Public HttpRequest request;
 Public HttpResponse response;
 Public Integer responseCode;
 Public String responseBody;
 Public Http httpObj;
 Public String clientCert;

 Public Static Final Integer HTTP_MAX_REQUEST_TIME = 120000;
 Public Static Final Boolean ENABLE_DEBUG_LOGS = TRUE;
 /*
  * Helper Methods - These do the actual work.
  */

 Public void buildRequest() {
  if (ENABLE_DEBUG_LOGS) {
   system.debug('Restclient buildRequest details' + headers + '
' +
     endpoint + '
' + method + '
' + body + 
     'set RestClient.ENABLE_DEBUG_LOGS = false to suppress this
      message');
  }
  //Create the httpRequest Object
  HttpRequest request = new HttpRequest();
  //Set the max timeout
  request.setTimeout(HTTP_MAX_REQUEST_TIME); 
  //Given a map<String,String> of header keys and values set 
  //them as request headers
  if (this.headers != null) {
   for (String headerName : this.headers.keySet()) {
    request.setHeader(headerName, headers.get(hkey));
   }
  }
  //Set the Endpoint
  request.setEndpoint(this.endpoint);
  //Set the Method
  request.setMethod(this.method);
  //Optionally set the body, if it's not blank or empty
  if (String.isNotBlank(this.body) && String.isNotEmpty(this.body)) {
   request.setBody(this.body);
  }
  this.request = request;
 }

Public void executeRequest() {
    if(this.request == null){
      this.buildRequest();
    }
    this.response = this.httpObj.send(request);
    if (response.getStatusCode() > 299) {
throw new RestClientException('Response Code was: ' +response.getStatusCode());
    }
  }
}

With this code, we've established some abstractions on the standard http callout functions provided by Salesforce. If we were to create a class extending our RestClient, we could make a request as simply as this:

public void makeApiCall(){this.endpoint = 'https://www.google.com?q=foo';this.method = 'GET';this.headers = new Map<String,String>();this.body = '';this.executeRequest();}

This is easier to follow and less verbose, but it's not as fluid and clear as it could be. We can take and abstract this one level further, establishing constructors and methods facilitating development as fluid as get(), patch(), put(), post(), and delete(). Building out these methods becomes a fairly simple matter, for example:

  public void get(){
    this.method = 'GET';
    this.executeRequest();
  }

Of course, this assumes that you've already set the endpoint and other details. Sometimes this is a valid assumption, other times, we may want to have a suite of convenience methods in our rest class that allow us to set the relevant details and execute the request all in one call. Unfortunately, this means that many small methods must be added to our RestClient, like these:

public void get(String endpoint, String body, 
  Map<String,String> headers){
  this.endpoint = endpoint;
  this.body = body;
  this.headers = headers;
  this.get();
}
  
  public void get(String endpoint, Map<String,String> headers){
    this.endpoint = endpoint;
    this.headers = headers;
    this.get();
  }
  
  public void get(String endpoint){
    this.endpoint = endpoint;
    this.get();
  }

Given these methods, any class that extends our RestClient has access to a set of get() methods accepting the full range of options. Thus, get('http://www.google.com'), get('http://www.codefriar.com', mapOfHeaders), and get('http://www.packtpub.com', 'body of request', mapOfHeaders) would all result in a get request being made, and the instance's response object being populated. As an exercise for the reader, you can create similar method sets for Put, Patch, Post, and Delete. Additionally, you can write these messages to automatically encode sObjects into JSON request body strings.

I mentioned earlier that I like to extend my rest class with an API class, and that class with individual request classes. Once a solid RestClient is established, it can be used for any API. However, just about every API I've ever integrated with has had its own quirks, especially around authentication. Additionally, there are some intelligent abstractions to be made on a per-API basis. For instance, when integrating with the Salesforce sObject API, all of our endpoints start with the same URL, that is, https://<instance>.salesforce.com/services/data/version/. The API class can establish a base URL, instance, and version like this:

public virtual class sObjectApiRestClient extends RestClient {

  private final string APIVersion = 'v35.0';
  private final string instance = 'na7';
  private string baseURL = 'https://' + 
instance +
'salesforce.com/services/data/' +
APIVersion + '/';
  private Map<String,String> additionalHeaders = new 
Map<String,String>();

  Public override void executeRequest() {
    //first set our endpoint by prepending it with our baseURL
    this.endpoint = this.baseURL + this.endpoint;
    if(this.request == null){
      this.buildRequest();
    }
    //Having built the request, inject headers for authentication
    injectAdditionalHeaders();
    this.response = this.httpObj.send(request);
    if (response.getStatusCode() > 299) {
      throw new RestClientException('Response Code was: ' +
 response.getStatusCode());
    }
  }

  private void injectAdditionalHeaders(){
    for(String h:additionalHeaders.keySet()){
    this.request.setHeader(h, additionalHeaders.get(h));
    }
  }
}

By overriding the executeRequest method, we get to make changes to the way all calls for this API are made; in this case, setting authentication headers. This way, all calls made by this API class will be made with the authentication headers we need for this API. We can also insert the retry logic and the logic for authenticating if we don't have a valid oAuth token. This override does not change our get(), put(), patch(), post(), and delete() methods. Hence, individual call classes can still use the get() helpers defined in RestClient, even as their executeRequest method is overridden.

When the API-specific class has been defined, it allows us to create classes that make and handle specific calls. For instance, in the sObject API, we have an account endpoint. If we extend our sObjectAPIRestClient class with an sObjectAccountApi class, we have a single place to encapsulate and store all of our account-related REST API calls:

public with sharing class accountSObjectRestClient {

  sObjectApiRestClient restClient;
  private string endpointPath = 'account/';

  public accountSObjectRestClient() {
    restClient = new sObjectApiRestClient();
  }

  public string getAccountById(Id id){
    restClient.get(endpointWithId(id));
    return restClient.responseBody;
  }

  public string updateAccountById(Id id, Account account){
    restClient.endpoint = endpointWithId(id);
    restClient.body = JSON.serialize(account);
    restClient.patch();
    return restClient.responseBody;
  }

  //Helper methods
  private string endpointWithId(Id id){
    return this.endpointPath + id;
  }
}

This is almost perfect! Our AccountSobjectRestClient class now has methods that abstract the implementation of how the API works. Once we've tested this, we'll easily be able to swap out the implementation of this API. There's one more thing we can do to make this usable—handling the translation of the response JSON into objects we can natively use. Writing JSON deserialization code is tedious at best and error prone at worst. Thankfully, a couple of amazing developers developed a web app that will automatically generate JSON deserialization code for you. Simply paste your JSON returned by the API into the box at json2apex.herokuapp.com, and name your deserialization class. When you click on Create Apex, you will download both the deserialization class and the tests for that class (yes, it generates the tests too!), as shown in the following screenshot:

Note the Create explicit parse code option. If your JSON requires explicit parsing because it contains, for instance, an Apex reserved word, this web app will automatically convert to using explicit parsing code. Because of this, you can effectively ignore that option. The code generated provides you with a static method called parse, which will return an object of the type you entered in the Name for the generated class field. In our example from the preceding screenshot, we'd receive back an object of the AccountRestResponses type. We can incorporate this into our accountSObjectRestClient class by modifying our methods to return the parsed object like this:

public accountRestResponses getAccountById(Id id){
  restClient.get(endpointWithId(id));
  accountRestResponse parsedObj;
  try{
    parsedObj = accoutRestResponses.parse(restClient.responseBody);
  } catch (JSONException jsone) {
    throw new RestClient.RestClientException(jsone);
  }
  return parsedObj;
}

Now, we have the full round trip package with a generic RestClient class with polymorphic versions for specific APIs that are used by object-specific classes with the ability to serialize and deserialize our data on the fly. With a system like this, you can integrate virtually any RESTFul API available. There are, of course, some limitations we need to be mindful of. The biggest limitation we need to track is the payload size. Asking an API to return 20,000 records may well be within the capabilities of that API, but Salesforce's ability to de-serialize and handle that many records depends on their size. Salesforce has a maximum response size of 6 MB. If your 20k records fit into a response of 6 MB, great! Otherwise, you'll have to request smaller batches of records. You also need to be mindful of the CPU time limit governor. If you can receive 20k records but not process them in time, you're still going to have to ask for smaller chunks. Regardless of its few limitations, the ability to make HTTP callouts to other APIs is an invaluable tool for building integrations between Salesforce and your external APIs.