View
11.547
Download
3
Category
Preview:
DESCRIPTION
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.
Citation preview
An introduction to consuming remote APIs
Pacific Northwest Drupal Summit10/16/2011
Joshua KopelPartner, Number 10 Web CompanyCTO/Co-founder, Squigaloo LLCTwitter:jkopeld.o:jkopel
An introduction to consuming remote
APIs• General overview and terms• A simple example• More complex considerations• Do’s and Don’ts• Tools and resources
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.
RESTful?
REpresentational State Transfer• Client / Server• Stateless• HTTP methods
There is also SOAP which is useful for transactional or sensitive information.
Remote APIs as:• Information sources
– Wunderground– Twitter
• Media sources– Flickr– YouTube
• Services– Google Charts– SalesForce
• Storage– Amazon S3– Google Cloud Storage
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
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
Be flexible
• Look for easy wins• Use modules where possible • Investigate the tradeoffs
CommonCraft
CommonCraft
Wistia as video CDN
Recurly for recurring subscription payments
Basic flow
Remote API
Format a request URI that references a resource and provides parameters.
Send request using http method (POST, GET, DELETE, etc).
Process request, format a response, and define a status.
Decode response and pass to appropriate consumer.
Check authentication and accept request.
Simple API example
GET https://api.wistia.com/v1/projects.json
Returns a list of all projectsParameter Description
sort_by
The name of the field to sort by. Valid values are “name”, “mediaCount”, “created”, or “updated”. Any other value will cause the results to be sorted by id, which is the default.
sort_direction (optional, defaults to 1)
This field specifies the direction of the sort. Valid values are 1 or 0, which specify ascending or descending order, respectively.
Fomatted URLGET 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
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);
Now what?
• Store– Entity– Table
• Display– As part of node or page– Dynamically with js
Building blocks
Security info in
variables
Admin configurati
on
API methods
Low level comm.
Remote API
Consuming code
(module hooks)
Building blocks
Security info in
variables
Admin configurati
on
API methods
Low level comm.
Remote API
Consuming code
(module hooks)
Security
$url = url('https://api:H7gd7n2yV9opM@ api.wistia.com/…
• SSL• http basic authorization• Domain keys/subdomains• OAuth
Building blocks
Security info in
variables
Admin configurati
on
API methods
Low level comm.
Remote API
Consuming code
(module hooks)
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
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);
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.
Building blocks
Security info in
variables
Admin configurati
on
API methods
Low level comm.
Remote API
Consuming code
(module hooks)
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.
Building blocks
Security info in
variables
Admin configurati
on
API methods
Low level comm.
Remote API
Consuming code
(module hooks)
Consuming Code
AKA “business logic”• Use hooks to trigger calls to the
remote.• Format results for display or storage.• Caching• Permissions
When to act
• On demand– hook_nnnnn_presave()– hook_nnnnn_load()– hook_nnnnn_view()– Ajax (menu) callback– Rule action
• Scheduled– hook_cron()
Things go wrong
• drupal_http_request is synchronous
• Use reasonable timeout values
• Cache if you can
Remote API
Play nice
• Don’t pound their servers• Cache if you can• Follow the rules• Find the communities and join in
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)
Thanks!
http://www.number10webcompany.com
Joshua KopelPartner, Number 10 Web CompanyCTO/Co-founder, Squigaloo LLCTwitter:jkopeld.o:jkopel
Recommended