The following is a portion of the notes that I took while viewing the Apex Training class, which is part of the Spring 2013 Premier Online Training available from Salesforce. This training class is one of the recommended training courses needed to complete the Salesforce Force.com Advanced Developer certification. Go here to get a PDF copy of the entire class notes.

Custom Web Services

• The webservice keyword allows developers to create their own SOAP Web Services and defines methods that are inherently global
• Two ways to invoke Web Services:
  • From the AJAX toolkit by importing the apex.js library and call the execute method
  • From a client program by importing the WSDL and calling the custom method directly
• Access WSDL support through Setup -> Develop -> Classes

Guidelines for Creating Custom Web Services

• Must be static and cannot be overloaded
• Method signatures cannot include exceptions, maps, sets, matchers, or patterns
• Webservice keyword cannot be used in any code contained in a trigger
•  A SOAP request or response cannot be bigger than 3MB
• The max size of the a SOAP request/response is regulated by the governor limit
• Webservice methods execute as System by default and can be changed with the “with sharing” keyword.
• @ReadOnly annotation can be used with web services to allow unrestricted queries when no DML operations are necessary.

SOAP Web Service Callouts

• Web services are called from external sources using SOAP Web Service Callouts
• Functionality is grouped based on business processes and is packaged as interoperable services.
• Functions are separated into distinct units or services, which are available over the network so that these can be combined and reused to produce business applications.
• External Web Services can be called natively from Apex by using SOAP Web Service Callouts

WSDL Support and Limitations

• Apex supports a limited set of WSDL schema types. It also supports the element and sequence WSDL schema constructs, as well as Blob, decimal and enum for call ins, but not for call outs.
• Apex does NOT support encoded services
• It also does not support WSD files with multiple portTypes, multiple services, or multiple bindings.
• WSDL files with imports are NOT supported
• It may be necessary to do a standard HTTP callout using a web services API such as RESTful web Services API.

HTTP Headers

• Can be set on a web service callout to set the value of a cookie in an authorization header.
• Can add inputHttpHeaders_x and outputHttpHeaders_c to an instance of your generated WSDL class.
• inputHttpHeaders is used to set authorization or cookie information
• outputHttpHeaders can be used to read the HTTP response headers returned after an HTTP request

Client Certificates

• Developers can send a client certificate with their callout to authenticate an HTTPS connection with a specified value.
• You can download a certificate through setup -> Security Controls -> Certificate and Key Management
• Create either a self-signed or CA-signed certificate
• Import the certificate on the remote application server that is being contacted as part of Web Service Integration
• You can also use Setup -> Developer -> API -> Generate Client Certificate to generate a client certificate for inbound calls, but not outbound ones.

Runtime Callout Considerations

• Request/Response must be no more than 3MB
• A short duration custom timeout can be defined
• A single Apex transaction can make a maximum of 10 callouts with a total request time of 120 seconds
• A circular reference can occur between Apex methods
• More than one loopback connections to Salesforce are not allowed
• To allow an endpoint to be accessed, it should be registered in Setup -> Security Controls -> Remote Site Settings. This is also known as whitelisting an endpoint, which tells Salesforce that it is ok to accept requests from this site.

Invoke an Imported web Service

• Successful importation of an external WSDL will generate an Apex stub (proxy) class
• Use the stub instance to setup your authorization credentials for the external service
• Use the stub to make external service method calls

RESTful Service Callouts

• Stands for Representational State Transfer
• Builds on the existing structure of the web by using HTTP verbs such as POST, GET, PUT, and DELETE
• A RESTFul service is called by hitting the resource URL, which can be pasted directly into a web browser (must be one line with no breaks).
• Simply sends and receives XML or JSON (Javascript Object Notation) data over HTTP
• Apex provides helper classes to parse and render XML and JSON data structures

XML Classes

• Callouts can be made from Apex where WSDL is not imported
• External web services can be accessed using HTTP callouts
• Send HTTP requests such as GET, POST, and PUT and also handle responses returned by request
• The XML Stream classes provide methods that make it easy to read and write XML strings
• XMLStreamReader class is used to read through XML responses returned from callouts and enables forward, read-only access to XML data returned from an HTTP callout
• XMLStreamWriter class is used to create an XML document and enables the writing of XML data.
• Document and XMLNode classes can be used as an alternative to XML classes

JSON Classes

• The JSON class provides methods to serialize and deserialize JSON content
• JSONGenerator class is used to serialize Apex objects into JSON content and enables the generation of standard JSON-encoded content
• JSONParser class is a parser for JSON-encoded content. It is used to parse a response that’s returned from a call to an external service that is in JSON format

Classes to make RESTful callouts

• HTTP class is used to sned an HTTPRequest and receive an HTTPResponse. It has only one method, send(), which takes one HTTPRequest argument and returns an HTTPResponse
• HTTPRequest class is used to programmatically create HTTP requests. It has several methods, such as:
  • setEndpoint
  • setBody
  • setHeader
  • setMethod
  • setClientCertificate
  • getEndpoint
  • getBody
  • getHeader
  • getMethod
• HTTPResponse class is used to programtically handle the HTTP response returned by HTTP. It has several methods, such as:
  • getStatus
  • getStatusCode
  • getHeader
  • getHeaderKeys
  • getBody
  • getXMLStreamReader

RESTful Callout Example

public class HttpCalloutSample {
//pass in the endpoint to be used using the string url
public String getContent(String url) {


     //Instantiate a new HTTP object
Http h = new Http();


     //Instantiate a new Http request, specify the method (GET) as well as the endpoint
HttpRequest req = new HttpRequest();
req.setEndpoint(url);
req.setMethod(‘GET’);
//Send the request and return a response
HttpResponse res = h.send(req);
Return res.getBody();
}
}

HTTP Helper Classes

• EncodingUtil class helps to encode and decode URL strings and includes the following methods:
  • Base64Decode – converts a Base64-encoded String to a Blob
  • Base64Encode – converts a Blob to an un-encoded string
  • convertToHex – returns a hexadecimal (base 16) representation of the input string
  • urlDecode – decodes a string using “UTF-8”
  • urlEncode – encodes a string
• Cryto class enables access to external services that require encryption and includes the following:
  • Encypt – encrypts the blob clearText using the specified algorithm. Use when you want to specify your own initialization vector
  • Decrypt – decrypts the blob cipherText using the specified algorithm
  • Sign – computes a unique digital signature for the input string using the supplied private key and the specified algorithm. This method supports the RSA-SHA1 or RSA algorithm
  • generateMAC – computes a message authentication code or MAC for the input string using the private key and specified algorithm. Supports the HmacSHA1 algorithm
  • generateDigest – computes a secure, one-way hash digest based on the supplied input string and algorithm name. Supports algorithms such as Md5 and SHA1
  • generateAESKey – generates an Advanced Encryption Standard (AES) key. You can size to specify the keys size in bits

  Apex REST-based Web Services

  • You can implement custom web services in Apex and expose them through the REST architecture by using Apex REST.
  • To do this, you first define your class with @RestResource annotation to expose it as a REST web service
  • You also annotate methods to be exposed with the appropriate HTTP method. The following methods are available:
    • HttpDelete
    • HttpGet
    • HttpPatch
    • HttpPost
    • HttpPut
  • You must define your methods as global static. For example:

  @RestResource (urlMapping=’/contact/v1/*’)
global class MyRESTService {
@httpPost
Global static Id doPost (String cLastName, Account a) {
Contact c = new Contact(LastName = cLastName, AccountId = a.Id);
Insert c;
Return c.id;
}
}

  Additional Apex Support for REST Web Services

  • RestContext object contains the RestRequest and RestResponse objects
  • Methods with @HttpGet or @HttpDelete annotations should have no parameters
  • Use user-defined types for parameters in Apex REST methods
  • JSON and XML formats are used to represent resources

  Using REST-based web Services

  • You can invoke a REST-based web service through an appropriate HTTP request and a URL, which includes a location of the Salesforce server, an Apex REST service, and a resource.
  • It is best to try and find an exact match. If you cannot find an exact match, then find all the patterns with wildcards that match, and then select the longest of those by string length. If you cannot find a wildcard match, then an HTTP response status code 404 will be returned.

  Asynchronous Apex

  • If any Apex process takes more than 5 seconds, you should consider moving it to asynchronous Apex.
  • To identify methods that are asynchronously executed, use the @future annotation. These must be static and can only return a void type
  • Use the @future annotation to make a web services callout from a trigger
  • A max of 10 method calls per Apex invocation are allowed
  • A max of 200 @future method calls per Salesforce license per 24 hours are allowed
  • The parameters passed to an asynchronous method must be primitive datatypes
  • Methods with the @future annotation cannot be used in getter/setter methods or constructors of Visualforce controllers
  • The asynchronous Apex code starts a new governor limit transaction context when it is run.
  • When you use a trigger to call an external service; that service needs to support batch processing similar to Force.com API; otherwise making 1 callout per record in a bulk trigger will quickly exceed governor limits