Creating Custom Apex REST Web Services

Force.com REST API is a powerful but generic way to access data. For some application-specific data access scenarios, such as those involving transactions that span multiple database objects, a custom API is helpful. You can expose your Apex classes as REST services, making simple atomic units of work accessible to callers outside of Force.com, and hiding the implementation details from them. Requests to custom Apex REST services are made via HTTP in JSON or XML format, dictated by the Content-Type header, with JSON the default.

For an Apex class to become a REST Web service, it must follow different rules than ordinary Apex classes. The most significant rules are listed here:

Global class access modifier—A class that contains any REST services must use the global access modifier. This means the class is visible to all programs running in the Force.com organization.

URL mapping annotation—A class containing REST services must be mapped to a URL so that it can be invoked. Define the URL mapping using the @RestResource annotation.

HTTP verb annotation—Each method accessible via REST must be annotated with a corresponding HTTP verb. The verbs are @HttpDelete, @HttpGet, @HttpPatch, @HttpPost, and @HttpPut, and the same verb can’t be assigned to more than one method. These methods must also be global and static.

Method parameters—The REST request body is automatically mapped into the parameters of the method. Method parameters are not supported for the @HttpDelete and @HttpGet verbs. The REST request URL is never automatically mapped to method parameters and requires code to extract its values.

Data types—Data types supported in REST methods are primitive types (except Blob and sObject), sObjects, List and Map (String keys only) containing primitives or sObjects, and user-defined classes.

Security—REST methods run as a system administrator, without regard for object-, field-, or record-level sharing rules. To enforce record sharing rules, define the class with the with sharing keyword. To enforce object- and field-level security, use the results of the getDescribe method (Schema.DescribeSObjectResult and Schema.DescribeFieldResult) to check the user’s permission to the data.

Supporting classes—User-defined Apex classes, inner or outer, that are arguments or return values for a REST service method must be defined as global.

Additionally, custom Apex REST Web services are subject to standard Apex governor limits. A subset of these governor limits is listed in Table 10.1.

Table 10.1 Subset of Apex REST Service Governor Limits

Listing 10.14 defines a simple Apex REST service that returns a record in the Project custom object given its unique identifier.

Listing 10.14 Custom Apex REST Web Service

Click here to view code image

@RestResource(urlMapping='/Listing10_14/*')
global with sharing class Listing10_14 {
  @HttpGet
  global static Project__c doGet() {
    RestRequest req = RestContext.request;
    String projectId = req.requestURI.substring(
      req.requestURI.lastIndexOf('/')+1);
    Project__c result = [SELECT Id, Name, Status__c, Owner.Name
      FROM Project__c WHERE Id = :projectId];
    return result;
  }
}

In Listing 10.15, the custom REST Web service is invoked and returns fields from the Project record with unique identifier a01i0000000rMq1.

Listing 10.15 Custom Apex REST Web Service Request and Response

Click here to view code image

curl -H 'Authorization: OAuth '$TOKEN -H "X-PrettyPrint:1"
 "https://na15.salesforce.com/services/apexrest/Listing10_14/a01i0000000rMq1"
{
  "attributes" : {
    "type" : "Project__c",
    "url" : "/services/data/v27.0/sobjects/Project__c/a01i0000000rMq1AAE"
  },
  "Name" : "GenePoint",
  "Owner" : {
    "attributes" : {
      "type" : "Name",
      "url" : "/services/data/v27.0/sobjects/User/005i0000000LUJsAAO"
    },
    "Name" : "Tim Barr",
    "Id" : "005i0000000LUJsAAO"
  },
  "OwnerId" : "005i0000000LUJsAAO",
  "Id" : "a01i0000000rMq1AAE",
  "Status__c" : "Green"
}