googleapis how google builds apis

7/28/2019 Googleapis How Google Builds Apis

1/95

How Google Builds APIs

Zach Maier, Mark Stahl,Joey Schorr, Yaniv Inbar

May 19-20, 2010


2/95


View live notes and ask questionsabout this session on Google Wave

http://bit.ly/apiwave#googleapis8


3/95



4/95


Google APIs 101


5/95


Google APIs 101

Making Future APIs Awesome


6/95


Google APIs 101


How Google ReallyBuilds APIs


7/95


Google APIs 101



Questions and Comments


8/95


Google APIs 101





9/95

REST == Representational State Transfer

Client and servers transferring resource representations

Good for cached and layered systems (like the web)

REST 101


10/95




In HTTP, this means verbs acting on resource URIs

GET http://gdata.youtube.com/feeds/api/channels

REST 101


11/95




In HTTP, this means verbs acting on resource URIs

GET http://gdata.youtube.com/feeds/api/channels

AtomPub models data as feedsofentries

Or more generally, as collectionsofresources

REST 101


12/95

REST 101


13/95

REST 101


14/95

REST 101


15/95

REST 101


16/95

REST 101


17/95

REST 101


18/95

REST 101


19/95

REST 101


20/95

REST 101


21/95

REST 101


22/95

Google Data


23/95

Google Data


24/95

Google Data Atom

Right now you MUST understand Atom to use the APIs.


25/95

Google Data Atom

Right now you MUST understand Atom to use the APIs

Core built around...

Atom Syndication Format (RFC4287)

Atom Publishing Protocol (RFC5023)


26/95

Google Data Atom

Right now you MUST understand Atom to use the APIs

Core built around...

Atom Syndication Format (RFC4287)

Atom Publishing Protocol (RFC5023)

Extended the core features

Query parameters

ConcurrencyBatch


27/95

Google Data

More than 25 APIs

More than 2B hits per day across all APIs.


28/95

The Future Google APIs

We're moving to a brand new API infrastructure


29/95


We're moving to a brand new API infrastructure

You might already be using it...


30/95


Google APIs 101

Making Future APIs AwesomeHow Google ReallyBuilds APIs



31/95


Rough edges in Google APIs

Output formats

Calling styles

Client libraries


32/95

Output Formats


33/95

Output Formats

Issue: Resources can be verbose


34/95

Output Formats

Solution: Allow operations on partial data


35/95

Output Formats


Partial Response: GET just the fields you want


36/95

Output Formats


Partial Response: GET just the fields you want

http://gdata.youtube.com/feeds/api/videos

?v=2&q=google%20io&max-results=1

&alt=xml

bit.ly/nopartial
http://bit.ly/nopartialhttp://bit.ly/nopartial


37/95

Output Formats


Partial Response:GET just the fields you want



&alt=xml

bit.ly/nopartial



&alt=xml&fields=entry(title,content)

bit.ly/partialon
http://bit.ly/partialonhttp://bit.ly/partialonhttp://bit.ly/partialonhttp://bit.ly/nopartialhttp://bit.ly/partialonhttp://bit.ly/nopartial


38/95

Output Formats





&alt=xml

bit.ly/nopartial




bit.ly/partialon

Partial Update: PATCH just the fields you retrieved


39/95

Output Formats





&alt=xml

bit.ly/nopartial




bit.ly/partialon

Partial Update: PATCH just the fields you retrieved

More documentation at http://bit.ly/partialops


40/95

Output Formats

Issue: XML isn't easy on all platforms


41/95

Solution: Support multiple read-write formats

Output Formats


42/95


Architecture Issue: Protocol-specific data model

Output Formats


43/95


Architecture Issue: Protocol-specific data model

Output Formats


44/95


Architecture Solution: Generic data model

Output Formats


45/95



Output Formats


46/95



http://www.googleapis.com/buzz/v1/activities

/markstahl/@public?q=google&max-results=1

&alt=atom bit.ly/buzzatom

http://www.googleapis.com/buzz/v1/activities

/markstahl/@public?q=google&max-results=1

&alt=json bit.ly/buzzjson

Output Formats
http://www.googleapis.com/buzz/v1/activities/markstahl/@public?q=google&max-results=1&alt=atom&prettyprint=truehttp://www.googleapis.com/buzz/v1/activities/markstahl/@public?q=google&max-results=1&alt=json&prettyprint=truehttp://www.googleapis.com/buzz/v1/activities/markstahl/@public?q=google&max-results=1&alt=atom&prettyprint=true


47/95



Output Formats


48/95



Output Formats


49/95

Calling Styles


50/95

Calling Styles

Issue: REST can be Awkward


51/95

Calling Styles



52/95

Calling Styles



53/95

Calling Styles


C lli S l


54/95

Calling Styles


C lli St l


55/95

Calling Styles

Solution: Augment REST with Custom Verbs

C lli St l


56/95

Calling Styles


C lli St l


57/95

Calling Styles


C lli St l


58/95

Calling Styles


C lli St l


59/95

Calling Styles


Example: Two ways to mark a task as "done"

C lli St l


60/95

Calling Styles



The RESTful way

GET /tasks/@me/{taskId}

modify resource on client, set the "done" bit

PUT /tasks/@me/{taskId}

C lli St l


61/95

Calling Styles



The RESTful way

GET /tasks/@me/{taskId}

modify resource on client, set the "done" bit

PUT /tasks/@me/{taskId}

Using custom verbs

POST /tasks/@me/{taskId}?method=markDone

Calling Styles


62/95

Calling Styles

Issue: RPC is the basis of many API Standards

Calling Styles


63/95

Calling Styles

Solution: Parallel REST and JSON-RPC interface

Calling Styles


64/95

Calling Styles


Calling Styles


65/95

Calling Styles


Parallel calling styles for common methods

Calling Styles


66/95

Calling Styles


Parallel calling styles for common methods, and custom verbs

Client Libraries


67/95

Client Libraries

Client Libraries


68/95

Client Libraries

Issue: Client libraries don't stay on the cutting edge

Client Libraries


69/95

Client Libraries

Solution: Dynamic Discovery

Client Libraries


70/95

Client Libraries


Discovery Document

JSON object

Describes resources, URLs, verbs, parameters, (schemas)

Always up to date

Client Libraries


71/95

Client Libraries


Discovery Document

JSON object

Describes resources, URLs, verbs, parameters, (schemas)

Always up to date

Discovery is just another API

http://www.googleapis.com/directory/v0.1/

describe?api=discovery&apiVersion=v1

bit.ly/buzzdiscovery

Client Libraries
http://bit.ly/buzzdiscovery


72/95

Client Libraries

Solution: "Generic" Client Libraries

Client Libraries


73/95

Client Libraries


Discover resources, URL templates, verbs

No more scraping URLs from doc

Client Libraries


74/95

Client Libraries




Use simple classes to represent resources

Create POJOs to map JSON

Client Libraries


75/95

Client Libraries






Make advanced features easy(er)

Batching, Async, Partial Get and Update

Client Libraries


76/95

Client Libraries








Works on multiple platforms

Java client works on servers, AppEngine, Android

JavaScript client works on web pages, gadgets, AppScript

Client Libraries


77/95

Client Libraries








Works on multiple platforms

Java client works on servers, AppEngine, Android

JavaScript client works on web pages, gadgets, AppScript

Release once ... Works with Any API


78/95

Java Client Demonstration

Client Libraries


79/95

Client Libraries


Client Libraries


80/95

Client Libraries


Why we like this client sample

Resource URLs are discovered dynamically

Very little Buzz specific code

Runs on Android

Client Libraries


81/95

Client Libraries


Why we like this client sampleResource URLs are discovered dynamically

Very little Buzz specific code

Runs on Android

Go check it out yourself!

Sample: bit.ly/iobuzz

Library:bit.ly/javalib

http://bit.ly/javalibhttp://bit.ly/iobuzzhttp://bit.ly/javalibhttp://bit.ly/iobuzz


82/95




83/95


Issues we've noticed in 5 years of building APIs

How we're fixing those issues



84/95

e utu e Goog e s


Resources can be verbose


Allow operations on partial data



85/95

g


Resources can be verboseXML isn't easy on all platforms



Provide multiple read-write formats



86/95

g



REST can be awkward




Augment REST with custom verbs, provide REST and RPC



87/95

g



REST can be awkward

Client libraries don't stay on the cutting edge




Augment REST with custom verbs, provide REST and RPC

Dynamic discovery and "generic" client libraries


88/95


Google APIs 101






89/95

g y



90/95

g y

Implement Internal Service

Define abstract resource (using protocol buffers)

Define collections and verbs (using protocol buffer RPC)



91/95

g y




Configure the API Stack

Map REST paths, RPC methods, query parametersAdd common functionality: auth, caching, logging, ...



92/95

g y




Configure the API Stack

Map REST paths, RPC methods, query parametersAdd common functionality: auth, caching, logging, ...

Write Output Templates

Set up external data representation

JSON, Atom, XML, ...


93/95

API Configuration Tool Demonstration



94/95

You just saw the simple three steps:

Service implementedAPI stack configured

Output templates written


95/95


Google APIs 101




http://bit.ly/apiwave

googleapis how google builds apis

Documents