Post on 14-Aug-2015
transcript
What is wrong with API wrappers and how can we do better
FILIPE XIMENES@xima
Recife
Recife
APIApplication Programming Interface
What???
◇ APIs define the interaction interface of a software.
◇ software might mean:○ a Python class○ a database○ some hardware○ some plugin○ a library○ a web service
Eg.: Python class
class User(object):
name = ''
email = ''
def update_data(self, name, email):
self.name = name
self.email = email
def talk(self, message):
print('{} says: {}'.format(self.name, message))
Eg.: web service
GET /v1/media/000000HOST: https://api.instagram.com
POST /v1/media/000000/commentsHOST: https://api.instagram.com
DELETE /v1/media/000000/comment/111111HOST: https://api.instagram.com
Integrating web services
I want to retrieve basic user data after he logs in using his facebook account.
Our options
◇ Option 1○ Read Facebook's API documentation.○ Use Python's urllib2 to make requests.
◇ Option 2○ Read Facebook's API documentation.○ Use Requests lib to make requests
◇ Option 3○ Search for an open source lib with ready to
go python methods for making endpoint requests.
○ Go to the beach.
Web API libs, aka web API wrappers◇ What is it?
○ Implementation of a web API documentation using a programming language.
◇ What is it for?○ Creates a layer over HTTP using your favorite
programming language■ authentication■ composing urls■ prepare requests■ process responses■ format data
facepy
facepy
from facepy import GraphAPI
graph = GraphAPI(oauth_access_token)
my_links = graph.get(path='me/links', page=True)
for link in my_links:
print(link) # link is a dict
facepy
graph = GraphAPI(oauth_access_token)
endpoint = '{}/{}'.format(user_id, 'statuses')
data = ??
user_data = graph.post(endpoint, **data)
Some notes
◇ Need to study facepy's documentation○ Request interfaces○ Parameter passing○ Response access○ Exception treatment
◇ Need to study Facebook's documentation○ Endpoints and HTTP methods available○ Parameters for each endpoint○ Data formatting for each request or response
python-twitter
python-twitter
import twitter
api = twitter.Api(consumer_key='consumer_key',
consumer_secret='consumer_secret',
access_token_key='access_token',
access_token_secret='access_token_secret')
statuses = api.GetUserTimeline(
user_id=user_uid, count=20,
since_id=id_of_first_tweet)
python-twitter
python-twitter
Some notes
◇ pydoc documentation◇ Not very pythonic code◇ No pagination support◇ A method for each endpoint◇ Models instead of dictionaries
I need a system that monitors Twitter, Facebook, Instagram, Blogger and Tumblr, to capture posts from each one of my users.
The ideal wrapper
◇ Authentication◇ Requests as the engine of requests◇ Pagination support (generators)◇ Exception raising according to error codes (403,
500...)◇ Hypermedia support (links, HATEOAS)◇ Explorable◇ Simple documentation
Tapioca Wrapper Delicious and comes in many flavours!
tapioca-wrapper
https://github.com/vintasoftware/tapioca-wrapper
What's tapioca-wrapper?Python framework to create web API wrappers
Demo time!!tapioca-facebook
Congratulationsyou now know how to use ANY tapioca wrapper
Developing a tapioca wrapper
The code
Pythonhttps://github.com/vintasoftware/tapioca-facebook/blob/master/tapioca_facebook/tapioca_facebook.py
Endpoint mappinghttps://github.com/vintasoftware/tapioca-facebook/blob/master/tapioca_facebook/resource_mapping.py
tapioca wrapper features
◇ A method for each endpoint◇ Explorable◇ Requests lib◇ Pagination support◇ Hypermedia support◇ Quick documentation access
~250 lines of code tapioca-facebook
~1,000 lines of codefacepy
~6,000 lines of code python-twitter
~150 lines of code tapioca-twitter
1 hourtapioca-parse
Notes
◇ We still need to read the API documentation but not the wrapper documentation.
◇ Fun to explore the package.◇ Writing new flavours:
○ Almost 100% declarative.○ Few lines of code.○ Batteries included.
◇ There's a lot more to improve.
QUESTIONS?
@ximagithub.com/filipeximenesximenes@vinta.com.brwww.vinta.com.br