"Managing API Complexity". Matthew Flaming, Temboo

COPYRIGHT TEMBOO 2013

Managing API Complexity

!  Matthew Flaming

!  Director of SW Development at Temboo.com

!  Live in Moscow (thanks, YaC!)


My Terrible Secret

!   I hate APIs

!   (except for yours)


One API is Great


Many APIs, not so much


Where are all the apps?

!  9,970 APIs as of this morning • programmableweb.com/apis/directory

!  There’s an explosion of amazing APIs on the web right now, but...

!  Most apps only connect to a single API (or a handful of similar APIs)


Two Problems

!  How do I connect to this API?

!  How do I make sure my app keeps working?


New learning curve per API !  How does this API conceptually fit together?

!  How does this API handle the details?

• Calling methods?

• Data formats? (JSON or XML?)

• Authentication?

• Language support?

• Dates? Boolean values? Pagination?

• Etc. etc.


More fragility per API

!  How to track API updates?

!  How to test API integration points?

!  How to effectively migrate between APIs?


This is an API publisher problem too

!   If you build it, they won’t (necessarily) come

!  …and if they do, they might hate you for it


How can API publishers help?

!  Thinking different isn’t always a good thing • REST is (usually) best

• Oauth 2.0 or HTTP Basic authentication

• Support both JSON and XML

• Keep your implementation details private



!  Understand that an API is a social contract • “It should keep working”

• Minimize churn

• Announce changes early, and loudly

• Bake in versioning

/myapi/v1.0/myresource



!  Discoverability is your most important feature • Documentation

• WSDL… or not

• JSON Discovery

www.googleapis.com/discovery/v1/apis

• Client libraries



!  Benefits of client libraries • Enforce API consistency

• Provide a test harness

• Reduce user friction

• Help you think like an API consumer


Code generation is the answer Expose language-agnostic metadata

github.com/wornik/swagger-codegen

var findById = {! 'spec': {! "description" : ”Find pet by ID",! "path" : "/pet.{format}/{petId}",! "summary" : "Find pet by ID",! "method": "GET",! "params" : [swagger.pathParam("petId", "ID of pet", "string")],! "responseClass" : "Pet",! "nickname" : "getPetById"! },! 'action': function (req,res) {! …function body here…! }!};!


Code generation is the answer Use metadata to generate client libraries

www.stringtemplate.org

/*!$description$!*/!var $nickname$ = function(! $params.fields:{paramName)$};separator=", "$,! callback, errorCallback) { ! ! var options = { !

!method: $method$, !!hostname: $host$, !!path: getReqPath($path$, $params$), !

}; ! var request = http.request(options, !

!function(response) { ! !responseHandler(response, callback,errorCallback); ! });!}!



!  Make your APIs device-friendly • Worry about data size

• Provide alternatives to Oauth


What about API consumers?

!  That’s all great, but…


What about API consumers?

!  Keep API integrations abstract and modular

!  Generalized open-source libraries

!  API management platforms • We all love infrastructure virtualization…

• What about… code virtualization?


Temboo

!  Collects and normalizes APIs to give you one consistent interface (“Choreographies”)

!  All the power of multiple APIs

!  Just one learning curve


Temboo


Temboo

!  Search Twitter (PHP) $session = new Temboo_Session('matthew', ’myApp', ’demo');!!// Instantiate the Choreo!$choreo = new Twitter_Search_Tweets($session);!!// Get an input object for the Choreo and set credential!$inputs = $choreo ->newInputs();!$inputs->setCredential('TwitterOAuthCredential');!!// Set inputs!$inputs->setQuery("Yac2013");!!// Execute Choreo and get results!$results = $choreo->execute($inputs)->getResults();!


Temboo

!  Search Flickr (PHP) $session = new Temboo_Session('matthew', ’myApp', ’demo');!!// Instantiate the Choreo!$choreo = new Flickr_Photos_SearchPhotos($session);!!// Get an input object for the Choreo and set credential!$inputs = $choreo ->newInputs();!$inputs->setCredential(’FlickrOAuthCredential');!!// Set inputs!$inputs->setText("Yac2013");!!// Execute Choreo and get results!$results = $choreo->execute($inputs)->getResults();!


Temboo

!  Search Dropbox (PHP) $session = new Temboo_Session('matthew', ’myApp', ’demo');!!// Instantiate the Choreo!$choreo = new Dropbox_FilesAndMetadata_SearchFilesAndFolders($session);!!// Get an input object for the Choreo and set credential!$inputs = $choreo ->newInputs();!$inputs->setCredential(’DropboxOAuthCredential');!!// Set inputs!$inputs->setQuery("Yac2013");!!// Execute Choreo and get results!$results = $choreo->execute($inputs)->getResults();!


Temboo

!  Search Foursquare (PHP) $session = new Temboo_Session('matthew', ’myApp', ’demo');!!// Instantiate the Choreo!$choreo = new Foursquare_Venues_SearchVenues($session);!!// Get an input object for the Choreo and set credential!$inputs = $choreo ->newInputs();!$inputs->setCredential(’FoursquareOAuthCredential');!!$inputs->setLatitude("40.7186300");!$inputs->setLongitude("-74.055840");!!// Execute Choreo and get results!$results = $choreo->execute($inputs)->getResults();!


Temboo

Choreography

Metadata

PHP template Node.js template Ruby template iOS template Python template

Java template cURL template Arduino template


Temboo

Choreography

Metadata

PHP template Node.js template Ruby template iOS template Python template

Java template cURL template Arduino template

Patch


Automation will transform APIs

!  Code generation + frameworks

!   Increasing standardization

!  Decreasing friction

!  An exciting time to be a developer


Thanks!

[email protected] @mflaming @temboo

"Managing API Complexity". Matthew Flaming, Temboo

Technology

Transcript of "Managing API Complexity". Matthew Flaming, Temboo