Your client says "Can we make the site work with snarkly.com? I hear they have a great API". What do you do? Don't panic! Working with remote services can be an incredibly powerful way to leverage the hard work of other developers and to build the capabilities of Drupal. Cool web services offering useful data and functions are proliferating like rabbits, and many have an API that they promote as "well documented and easy to use". Sometimes this is even true. We will look at two such services and review the basic building blocks of modules to interact with them.

1. An introduction to consuming remote APIs Pacific Northwest Drupal Summit 10/16/2011 Joshua Kopel Partner, Number 10 Web Company CTO/Co-founder, Squigaloo LLC Twitter:jkopel d.o:jkopel

2. An introduction to consuming remote APIs General overview and terms A simple example More complex considerations Do’s and Don’ts Tools and resources

3. Today We are talking specifically about RESTful interaction berween Drupal (7) and remote web services over HTTP using JSON, XML, or a variety of other languages.

4. RESTful? REpresentational State Transfer Client / Server Stateless HTTP methods There is also SOAP which is useful for transactional or sensitive information.

5. Remote APIs as: Information sources Wunderground Twitter Media sources Flickr YouTube Services Google Charts SalesForce Storage Amazon S3 Google Cloud Storage

6. The Drupal way Pro Write minimal code! Feeds, Rules, Entities Easily modified Fully integrated with the rest of Drupal Con Difficult to manage complex interactions Implementation scattered across modules Performance challenges

7. The coder way Pro Write fast code Build a useful API for other modules Manage complex interactions in code Con Must expose data in order to integrate Overhead, maintenance, security, updates

8. Be flexible Look for easy wins Use modules where possible Investigate the tradeoffs

9. CommonCraft

10. CommonCraft Recurly for recurring subscription payments Wistia as video CDN

11. Basic flow Format a request URI that references a resource and provides parameters. Send request using http method (POST, GET, DELETE, etc). Decode response and pass to appropriate consumer. Remote API Process request, format a response, and define a status. Check authentication and accept request.

12. Simple API example GET https://api.wistia.com/v1/projects.json Returns a list of all projects

13. Fomatted URL GET https://user:password@api.wistia.com/v1/ projects.json?sort_by=created&sort_direction=0 https://user:password@api.wistia.com/v1 secured URL projects resource .json language ?sort_by=created&sort_direction=0 Url encoded list of parameters Returns a list of all projects sorted by creation date in descending order

14. Basic code $query = array('sort_by' => 'created', 'sort_direction' => 0); $options = array('query' => $query, 'https' => TRUE); $url = url('https://usr:pass@api.wistia.com/v1/projects.json', $options); $options = array('method'=>'GET'); $result = drupal_http_request($url, $options); $json = json_decode($result->data); -or- $xml = simplexml_load_string ($result);

15. Now what? Store Entity Table Display As part of node or page Dynamically with js

16. Building blocks Consuming code (module hooks) Admin configuration API methods Security info in variables Low level comm. Remote API

17. Building blocks Consuming code (module hooks) Admin configuration API methods Security info in variables Low level comm. Remote API

18. Security $url = url('https://api:H7gd7n2yV9opM@ api.wistia.com/… SSL http basic authorization Domain keys/subdomains OAuth

19. Building blocks Consuming code (module hooks) Admin configuration API methods Security info in variables Low level comm. Remote API

20. Low level communication Standard functions to: Format URL(s) Format headers & http method Format query strings Request data Read http status Perform error checking on inbound data

21. Sending data Usually uses the POST method Build an array of encoded parameters Serialize binary data - base64_encode() $headers = array('Content-Type' => 'application/x-www-form-urlencoded') $query = drupal_http_build_query(array('name' => $name)); $options = array(‘headers'=>$headers, 'method'=>‘POST', 'data'=>$query); $result = drupal_http_request($url, $options);

22. Sending LOTS of data Files can be sent and retrieved using stream wrappers. Wraps a remote API and creates an addressable protocol (i.e. youtube://) It is a whole other session.

23. Building blocks Consuming code (module hooks) Admin configuration API methods Security info in variables Low level comm. Remote API

24. API methods Map the remote API to what your module needs. Parse decoded data and return only what is needed. Format data for transfer to remote API. Return meaningful error messages based upon context.

25. Building blocks Consuming code (module hooks) Admin configuration API methods Security info in variables Low level comm. Remote API

26. Consuming Code AKA “business logic” Use hooks to trigger calls to the remote. Format results for display or storage. Caching Permissions

27. When to act On demand hook_nnnnn_presave() hook_nnnnn_load() hook_nnnnn_view() Ajax (menu) callback Rule action Scheduled hook_cron()

28. Things go wrong drupal_http_request is synchronous Use reasonable timeout values Cache if you can Remote API

29. Play nice Don’t pound their servers Cache if you can Follow the rules Find the communities and join in

30. Useful tools Debugger Xdebug http headers “sniffer” Live http headers extension (FF) HTTP Headers (chrome) A reverse proxy / http monitor Charles (http://www.charlesproxy.com/) HttpFox (FF)

31. Thanks! http://www.number10webcompany.com Joshua Kopel Partner, Number 10 Web Company CTO/Co-founder, Squigaloo LLC Twitter:jkopel d.o:jkopel