For a large development team or ISV, building an external API on Heroku for Force.com allows you to share your processes and data with your ecosystem, while limiting their access. Through a real-world example, you'll learn how to design an eloquent RESTful API using JSON and OAuth, when to use Apex REST Services over the REST API, and when to add functionality to your org versus your API. Join us as we outline approaches for user-level security, key-based authorization, versioning of Salesforce assets, caching strategies, throttling, testing, and much more.

1. Build your API with Force.com &
Heroku
Jeff Douglas, Appirio, CloudSpokes Platform Architect
@jeffdonthemic

2. Jeff Douglas
CloudSpokes Platform Architect
@jeffdonthemic

3. All about CloudSpokes
CloudSpokes is a crowdsourcing development community
where members compete in design, coding and algorithm
challenges for cash, prizes, badges and bragging rights.
§ ~600,000 member community
§ 40-60 challenges in-flight at any one time
§ Force.com platform manages members, challenges, payments, etc.
§ API calls Force.com via REST and JSON

4. Why build an API?
§ IT departments can provide limited access
to internal development teams without
exposing the implementation details of
Salesforce.com
§ ISVs can better serve existing customers
by extending their platform
§ Startups and entrepreneurs can build their
business upon Force.com

5. Why choose Force.com?
§ Build your business logic in Apex
§ No admin UI to develop and maintain
§ Security -- FTW!
§ Declarative development
§ Reports & dashboards
§ Sandbox environments, tools, deployment processes, etc.

6. Why choose Heroku?
§ Scale up and down rapidly
§ Fork applications for testing, QA, etc.
§ Distributed development with Git
§ Postgres (fork, follow, share)
§ Heroku add-ons
§ Free to get started
§ Excellent support

7. Designing your API
Developers want the following:
§ Simple, intuitive and easy to learn
§ Great documentation
§ Code samples
§ Test cases

8. Building your API
Adopt web standards. Don’t reinvent the wheel.
§ REST
§ JSON
§ OAuth 2

9. Use proper REST principles
Nouns are good. Verbs are bad.

10. Other API design considerations
§ HTTP response and error codes
§ Versioning (header vs. URL)
§ Key management & security
§ Hide complexity behind “?”
Poor design: /challenges/open/5
Better design: /challenges?status=open&limit=5
Teach a Dog to REST

11. Which development language is best?
Language specific REST wrappers for Force.com as well as tools
to make it easier to build well-designed APIs.
§ Ruby
• restforce gem, forcifier gem
• Rocket_pants, Grape
§ Node.js
• nforce package, forcifier-node package
• Actionhero, Restify, Express
§ Java
• Play!, Jersey

12. Apex REST Services vs. REST API
The REST API is great for interacting with records while Apex
REST Services can encapsulate numerous operations into a
single request.
§ Design to run as quickly as possible
§ Handoff long running requests to asynchronous processes

13. Let’s build an API!

14. User authentication
Authentication your API with Force.com
§ Single “shared” user
§ Named user
• Security
• Chatter
• Audit trail & history
• Record ownership

15. Best practices
§ Prototype with REST API then port to Apex REST
§ Caching is cheap and fast with Memcache and redis
§ Sync to local datastore with Cloudconnect.com
§ Think about how to version Apex classes, triggers and workflows

16. Development tools
§ Workbench
§ Runscope for debuging, testing and sharing API calls
§ Chrome extensions: Postman, REST Console
§ IODocs for documenting and testing calls

17. Force.com Gotchas!
§ Salesforce.com maintenance downtime
§ Hard to write unit tests with sandbox environments
§ Sandbox refreshes

18. Jeff Douglas
CloudSpokes Platform
Architect,
@jeffdonthemic