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