Getting Started With Apex REST Services
4 likes5,623 views
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.
Getting Started With Apex REST Services
- 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.
- 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
- 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