This document provides an overview and introduction to creating and using Apex REST services in Salesforce. It begins with defining what REST is and the benefits of using Apex REST. It then demonstrates how to create a basic Apex REST service by annotating an Apex class and methods. Examples are provided of querying and returning data from a simple REST service. The document also discusses additional techniques for handling input and output through REST services like supporting different HTTP methods and using wrapper classes.

1. Getting Started with Apex REST
Services
Matthew Lamb, Appirio, Technical Architect
@SFDCMatt

2. Safe Harbor
Safe harbor statement under the Private Securities Litigation Reform Act of 1995:
This presentation may contain forward-looking statements that involve risks, uncertainties, and assumptions. If any such uncertainties
materialize or if any of the assumptions proves incorrect, the results of salesforce.com, inc. could differ materially from the results
expressed or implied by the forward-looking statements we make. All statements other than statements of historical fact could be
deemed forward-looking, including any projections of product or service availability, subscriber growth, earnings, revenues, or other
financial items and any statements regarding strategies or plans of management for future operations, statements of belief, any
statements concerning new, planned, or upgraded services or technology developments and customer contracts or use of our services.
The risks and uncertainties referred to above include – but are not limited to – risks associated with developing and delivering new
functionality for our service, new products and services, our new business model, our past operating losses, possible fluctuations in our
operating results and rate of growth, interruptions or delays in our Web hosting, breach of our security measures, the outcome of any
litigation, risks associated with completed and any possible mergers and acquisitions, the immature market in which we operate, our
relatively limited operating history, our ability to expand, retain, and motivate our employees and manage our growth, new releases of our
service and successful customer deployment, our limited history reselling non-salesforce.com products, and utilization and selling to
larger enterprise customers. Further information on potential factors that could affect the financial results of salesforce.com, inc. is
included in our annual report on Form 10-K for the most recent fiscal year and in our quarterly report on Form 10-Q for the most recent
fiscal quarter. These documents and others containing important disclosures are available on the SEC Filings section of the Investor
Information section of our Web site.
Any unreleased services or features referenced in this or other presentations, press releases or public statements are not currently
available and may not be delivered on time or at all. Customers who purchase our services should make the purchase decisions
based upon features that are currently available. Salesforce.com, inc. assumes no obligation and does not intend to update these
forward-looking statements.

3. Matthew Lamb
Technical Architect
@SFDCMatt

4. Helping Enterprises Become:
Efficient
Effective
Agile
Social
Mobile

5. Session Objectives ==
▪ Briefly define, what is a REST service?
▪ How to create custom REST services in Apex
▪ How to call those custom REST services
▪ Tips-and-Tricks / Do’s and Don’ts / Code Sample

6. Session Objectives !=
▪ SOAP
▪ Web service design patterns / philosophies
▪ Security relevant to a public API
▪ Programmatic authentication into Salesforce

7. By a show of hands…
▪ Apex SOAP web services
▪ RESTful web service protocols
▪ Native REST API
• Know about it?
• Used it?

8. What is REST?
▪ Representational State Transfer
▪ REST is:
• An architecture style, not a protocol
• HTTP-based
• Client-server
• Stateless

9. What is REST?
▪ Uses standard HTTP methods, sent to an endpoint
• POST, GET, DELETE, PUT, PATCH
• https://na10.salesforce.com/services/apexrest/myaccountservice/
▪ Receive a response payload and a status in return
• JSON or XML
• 200 (OK), 404 (Not Found), etc -> bit.ly/responsecodes
▪ Commonly, HTTP verbs are mapped to CRUD operations
• POST = Create
GET = Read
DELETE = Delete
PUT/PATCH = Update

10. Why Use Apex REST?
▪ All sObjects, standard or custom, come with a REST API
▪ Apex REST used for defining custom interactions
▪ Good for abstracting complex interactions to a single call
• Inserting / updating multiple objects
• Callouts to external systems
• Custom search interfaces

11. Apex REST Basics
▪ All custom Apex REST services are accessed in the same namespace
• /services/apexrest/
• https://na15.salesforce.com/services/apexrest/<custom_path>
https://na10.salesforce.com/services/apexrest/v1/joborders
Base URL (your org)
Apex REST Namespace
Your custom path

12. Apex REST Basics
▪ If you know Apex…
▪ @RestResource(urlMapping=‘/<custom_path>/*’)
• Class level annotation to define a Global Class as an Apex REST service
• custom_path is a customizable URL you define for your end point
▪ @HttpPost, @HttpGet, @HttpDelete, @HttpPut, @HttpPatch
• Method level annotations to map HTTP methods functionality

13. Apex REST Basics
▪ RestContext class
• Container class for the RestRequest and RestResponse objects
• bit.ly/RestContext
▪ RestRequest and RestResponse
• Aptly named classes instantiated for each call to an Apex REST endpoint
• bit.ly/RestRequest
• bit.ly/RestResponse

14. Apex REST Basics
▪ RestRequest
• Provides access to all aspects of the request
• Inbound requests are automatically deserialized into a RestRequest instance
• headers, httpMethod, params, remoteAddress, requestBody, requestURI, resourcePath
▪ RestResponse
• Provides access to all aspects of the response
• statusCode, responseBody, headers
• Method return value is automatically serialized into the reponseBody

15. A Simple Apex REST Service
▪ REST_AccountService_V1
• Given an Account External Id, return a few details about the Account
• Endpoint is /v1/accounts/*, which means the service is at:
– https://na15.salesforce.com/services/apexrest/v1/accounts/
• @HttpGet method will take in an Account Id and return several data points about
that Account

16. Calling our simple Apex REST service
▪ GET @ /services/apexrest/v1/accounts/1006
• Success!
• https://na15.salesforce.com/services/apexrest/v1/accounts/1006
• JSON or XML
• Changes available in real time
▪ GET @ /services/apexrest/v1/accounts/6654
• Fail!
• Error handling

17. We can make him better than he was
▪ REST_AccountService_V2
• Success!
• Automatic serialization FTW!
– Apex primitives (excluding Blob)
– sObjects
– Lists or maps (with String keys) of Apex primitives or sObjects
– User-defined types that contain member variables of the types listed above

18. Operating on the resource and its entities
▪ So far we’ve been operating only on specific entities
• /v2/accounts/1003
▪ REST_AccountService_V3
• Maintain existing record lookup via foreign key
– /v3/accounts/1023
• Query string provides search capabilities
– /v3/accounts?Name=United

19. We GET it, what’s next?
▪ POST, PUT, PATCH, DELETE
Resource
accounts/
accounts/1147
GET
POST
PUT/PATCH
DELETE
Search Accounts
Create a new Account
Error
Error
Retrieve a specific
Account
Error
Update a specific Account
Remove a specific Account
▪ Verbs -> CRUD is oversimplifying it a bit
• bit.ly/PutOrPost

20. Let’s try POST on for size
▪ REST_AccountService_V4
• Should feel familiar
• Request body is required for POST
• Parameters map to method signature
• Same error handling principles apply
▪ Method definition strictly defines what can be passed
• Might be great for your use case, might not
• If you need more flexibility…

21. Several more flexible ways to allow input
▪ REST_AccountService_V5
• Your POST (or PUT or PATCH) method can take sObjects
• If you include a valid field, it’ll be deserialized into the sObject instance
▪ REST_AccountService_V6
• You could also take Lists of sObjects!
▪ REST_AccountService_v7
• Or even wrapper classes!

22. What’s next?
▪ PUT / PATCH / DELETE
▪ Similar to what you’ve seen today
▪ Write test coverage
▪ Download all the code
▪ http://github.com/sfdcmatt/DF13ApexRest

23. Matthew Lamb
Technical Architect
@SFDCMatt

24. We want to hear
from YOU!
Please take a moment to complete our
session survey
Surveys can be found in the “My Agenda”
portion of the Dreamforce app