The code used in this section uses Apex test methods (not included in the FormulaForce application). As an easy way to run API code examples, we will be using an Apex Test to illustrate the use of Apex APIs from the sample code included in this chapter. The two test methods we will look at call the compliance API after calling the season API to create some test data (which, of course, only exists on the database within the scope of the test execution).

In the following examples, the Driver records created by the SeasonService.createTestSeason API do not indicate that the drivers hold FIA Super License. Thus, the expectation is that the ComplianceService.verify method will throw an exception reporting this problem. The following example test code asserts this behavior purely for illustration purposes in this chapter:

@IsTest
private class ApplicationAPITest {
    @IsTest
    private static void demoComplianceVerifyAPI() {
        // Create some test data via the SeasonService
        fforce.SeasonService.createTestSeason();
        
        // Query Drivers to test compliance against
        Map<Id, fforce__Driver__c> driversById =
            new Map<Id, fforce__Driver__c>([select Id from fforce__Driver__c]);
        
        try {
            // Invoke the compliance engine for the drivers
            fforce.ComplianceService.verify(driversById.keySet());
            System.assert(false, 'Expected failures'),
        } 
        catch (fforce.ComplianceService.ComplianceException e) {
            // Check the results
            System.assertEquals('4.1', e.failures[0].complianceCode);
            System.assertEquals('Driver must have a FIA Super License.',e.failures[0].failureReason);
        }
    }
}

Run the test to confirm whether the API is working as expected.

Notice that when you click on the Show Dependencies button in the ApplicationAPITest class, it shows the API and Custom Objects being referenced from the package:

Once a global class method or member has been published by including it in a released package, it cannot be removed or changed. For example, try changing the ComplianceService.verify method by renaming it to verification (for example). When you attempt to save the class, you will receive the following error:

(ComplianceService) Global/WebService identifiers cannot be removed from managed application: Method: void verify(SET<Id>)  (Line: 1)

The @Depreciated annotation can be used to effectively remove from visibility the class, interface, method, or member that global has been applied to from the perspective of subsequent package version consumers. Developer X can still access the deprecated items by referencing an earlier version of the package through the class version settings shown via the Version Settings tab as described in more detail in the following sections:

When saved, the ApplicationAPITest class, the Version Settings tab, and the Dependencies page reflects the fact that code within the class is referencing the ComplianceService and SeasonService classes from the FormulaForce package.

In the following screenshot, the version is shown v1.8 as this was the current version of the package when the Apex class was first created (this might be different in your case, depending on how many times you have uploaded the package so far):

In the following steps, we will release a new version of the package with a new Compliance API to explore how the platform provides Apex API versioning:

Attempt to add the following new test method and save the class:

    @IsTest
    private static void demoComplianceReportAPI() {
        // Create some test data via the SeasonService
        fforce.SeasonService.createTestSeason();
        
        // Query Drivers to test compliance against
        Map<Id, fforce__Driver__c> driversById =
            new Map<Id, fforce__Driver__c>(
               [select Id from fforce__Driver__c]);
            
        // Update the licenses for the drivers
        for(fforce__Driver__c driver : driversById.values())
            driver.fforce__FIASuperLicense__c = true;
        update driversById.values();
            
        // Invoke the compliance engine to verify the drivers
        List<fforce.ComplianceService.VerifyResult>reportResults =             fforce.ComplianceService.report(driversById.keySet()); 
            
        // Check the results
        System.assertEquals('4.1',reportResults[0].complianceCode);
        System.assertEquals(true, reportResults[0].passed);
        System.assertEquals(null,reportResults[0].failureReason);
    }

You should get an error, indicating that the method does not exist:

Compile Error: Package Visibility: Method is not visible: fforce.ComplianceService.report(SET<Id>) at line 21 column 13 

This is due to the package version information in the Apex class metadata of the test class still referencing the release of the package installed at the time the code was originally written. Upgrading the package does not change this. Open the Version Settings tab and change to the release you have just installed to fix this compile problem

The preceding steps have illustrated how the Apex runtime manages versioning of the Apex APIs you expose from your package. Thus, the requirement of versioning API definition described earlier has been provided by the platform for you. There is no need to manage this yourself, though you do need to be aware of how it works.

Finally, revisit the ComplianceService Apex class page from within your test development org and notice that the available versions of this class has also increased to include the version just uploaded. Toggle between them; you can see the changes that the API definition has undergone between the last two package releases we have just performed.

Select All Versions to get a full summary of which methods arrived at which package version. You can see in the following screenshot that the verify method was first available in v1.8 and the report method in v1.9; again, your version numbers might differ:

The API definition is not the only aspect that can undergo changes between releases. Even if the definition stays the same, the code behind it can change the behavior of the API. The Apex runtime provides a means for the packaged code to determine which version the calling code written by Developer X is expecting. This can be obtained by calling the System.requestVersion method. With this information, your packaged code can modify its behavior according to the expectations of the calling code.

As you release more versions of your package and the functionality grows, the management of this type of code becomes more complex. Also note that this feature is only available in the code located within the packaging org or specifically managed code. In the standard developer org, this method will throw a runtime exception. This essentially rules out its use if you plan on relocating your code outside the packaging org, for example, by following the team development model discussed in the last chapter of this book.

Another way of versioning behavior is by considering whether changes in your application logic are something that Developer X would want to opt in to or be immediately available to their existing code once the package is upgraded. Changes to fix bugs or minor improvements in the way information is processed are likely things you wish to be available, regardless of the API version. However, other changes such as the way values are calculated or the addition of significantly new processing would be something that might justify a new API method or a parameter for Developer X to modify their code to use. Much like in the UI, you will choose to add a new tab, page, or button.

By considering when to version the API behavior, you have put the choice as to when to accept new API behaviors in the hands of Developer X. Critically, by considering backwards compatibility you have not blocked upgrading to the latest version of your package due to integration failures. Spotting backwards compatibility regressions caused by behavior changes will get harder the more versions you release and the more supported versions you have in your customer base. Therefore making sure that you have a strong API-testing strategy becomes all the more critical.

In the RESTful world, your operations are associated with a resource that is expressed via Uniform Resource Identifier (URI). A resource can be a physical thing in your application such as a Custom Object, or a conceptual thing. This is different from the Service layer design that drove the Apex API we have looked at earlier, where operations are expressed by grouping them under functional areas of the application, which are then expressed by Apex Service classes and methods for each operation.

The Salesforce REST API uses Custom Objects to define physical resources the REST URI uses, allowing you to build a URI and use the various HTTP methods to perform the create, read, update, and delete operations. For example, to retrieve a record you can issue the following request via the Developer Workbench tool:

In cases where you are exposing more business process or task-orientated operations that are not data-centric, it can be difficult to decide what the resource name should actually be? So it is worth taking the time to plan out and agree with the whole product team what the key REST resources are in the application and sticking to them.

One operation that falls into this category in our FormulaForce package is the compliance report. This operates on a number of different Custom Object records to report compliance, such as the driver, car, and team. Should we define a URI that applies it to each of these physical resources individually, or create a new logical compliance resource?

I chose the latter in this chapter because it feels more extensible to do it this way, as it also leverages the compliance service in the application, which already supports adding new object types to the compliance checker. Thus, the REST API will support new object types without future changes to the API, as they are added to the compliance checker.

Salesforce dictates the initial parts of the URI used to define the resource and the developer gets to define the rest. For the compliance REST API, we will use this URI:

/services/apexrest/compliance

Once you package your Apex code implementing this REST API, you will find that the preceding URI needs to be qualified by your package namespace, so it will take on the format, shown as follows, from the point of view of Developer X, where fforce is my namespace. We will use this format of URI when we test the compliance REST API later in this chapter:

/services/apexrest/fforce/compliance

Your application operations for a given resource URI should be mapped to one of the standard HTTP methods on which REST is based: GET, POST, PUT, PATCH, and DELETE. Choosing which to use and being consistent about its use throughout your REST API is vital. Again, there are many resources on the Internet that discuss this topic in much more detail. Here is a brief summary of my interpretation of those readings:

We will use the POST HTTP method with the /services/apexrest/compliance resource URI to implement our REST API for the compliance verify operation, passing the list of records to verify as a part of the HTTP request body using the JSON data format.

The Salesforce REST API, and any Apex REST APIs exposed, can receive from a new HTTP header, such as x-sfdc-packageversion-fforce: 1.10. In the case of Apex REST APIs, this can be used to allow the packaged API code to implement behavior versioning. This can be used to set the version returned by System.requestVersion as described earlier in this chapter.

This header is optional; without it, the current package version installed is assumed. My preceding recommendations around the utilization of behavior versioning also apply here. Because the header is optional, its usefulness is diluted.

The preceding HTTP header does not affect the visibility of the API's definition in the same way that the platform does for Apex API's as illustrated earlier in the chapter. One option to address this is to map a versioned URI to a specific Apex resource class per version, for example, to support version v1.0 and v2.0 of the compliance REST API. This approach allows you to expose URI's with your version included:

/service/apexrest/fforce/v1.0/compliance
/service/apexrest/fforce/v2.0/compliance

When versioning the API definition, you would need to also capture copies of the Apex data types used in the Service layer. This would isolate each REST API version from underlying changes of the Service layer as it evolves. The main coding overhead here is going to be marshaling between the Apex types defined in the Service layer (which are always the latest version) and those in the class implementing the REST API.

For example, to version the report API, we have to capture its types as inner Apex classes at the time the API class is created. The following example illustrates this for v1.0. You can see how the definition of the API can be encapsulated within the specific version of the Apex class denoted by the v1_0 suffix:

@RestResource(urlMapping='/v1.0/compliance')
global with sharing class ComplianceResource_v1_0 {
  global class VerifyResult {
    global Id recordId;
    global String complianceCode;
    global Boolean passed;
    global String failureReason;
  } 
  @HttpPost
  global static List<VerifyResult> report(List<Id> Ids) {
    List<VerifyResult> results = new List<VerifyResult>();
    for(ComplianceService.VerifyResult result : 
      ComplianceService.report(new Set<Id>(Ids)))
    results.add(makeVerifyResult(result));
    return results;
  }
  private static VerifyResultmakeVerifyResult(ComplianceService.VerifyResult verifyResult){
    VerifyResult restVerifyResult = new VerifyResult();
    restVerifyResult.recordId = verifyResult.recordId;
    restVerifyResult.complianceCode = verifyResult.complianceCode;
    restVerifyResult.passed = verifyResult.passed;
    restVerifyResult.failureReason = verifyResult.failureReason;
    return restVerifyResult;
  }
} 

While the version number you use can be anything you like, you may want to consider following your package version numbering sequence.

Versioning Apex REST APIs this way is not ideal due to the manual way in which the definition has to be versioned by code and the overhead in managing that code for each release of your package. However, without this approach, it is always the latest definition of the Apex REST API in your package that is exposed.

This means that after upgrades of your package callers receive new fields in responses they do not expect. There is also no way to deprecate Apex REST APIs. However due to the deletion restrictions over the global class members, there is some protection over developers in accidentally removing fields that would break existing requests.