Getting Started with Apex REST ServicesMatthew Lamb, Appirio, Technical Architect@SFDCMatt

Safe HarborSafe 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.

Matthew LambTechnical Architect@SFDCMatt

Helping Enterprises Become:Efficient Effective

Social MobileAgile

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

Session Objectives !=▪ SOAP

▪ Web service design patterns / philosophies

▪ Security relevant to a public API

▪ Programmatic authentication into Salesforce

By a show of hands…▪ Apex SOAP web services

▪ RESTful web service protocols

▪ Native REST API• Know about it?• Used it?

What is REST?▪ Representational State Transfer

▪ REST is:• An architecture style, not a protocol• HTTP-based• Client-server• Stateless

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

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

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

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

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

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

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

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

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

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

We GET it, what’s next?▪ POST, PUT, PATCH, DELETE

▪ Verbs -> CRUD is oversimplifying it a bit• bit.ly/PutOrPost

Resource GET POST PUT/PATCH DELETE

accounts/ Search Accounts Create a new Account Error Error

accounts/1147 Retrieve a specific Account Error Update a specific Account Remove a specific Account

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…

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!

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

Matthew Lamb

Technical Architect@SFDCMatt

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