Adoption-Centered API Design

Adoption-Centered API DesignMarsh Gardiner, @earth2marsh

Brian Mulloy, @landlessness

2

Integers as a Service

3

Overview

• How did we get here?• Where are we now?• Where are we going?• How are we going to get there?• Questions

How did we get here?

5

In the beginning…

6

SOAP and XML-RPC

7

REST

8

The rise of…

• Software as a Service• Web Mashups• Virtualization• User Experience• Mobile

9

Web vs App

10

Technology unlocks technology…

11

Gehry vs Winnebago

photo: uggboy

Where are we now?

13

Refocusing API design

14

Passion (and controversy)

15

Design for adoption

16

Resource

Addressing:

IP: 173.194.70.102 google.com➡

Twitter: 14352786 @earth2marsh➡

https://github.com/apigee

17

Verb

18

General philosophy

Applying RV patterns

20

Collections and entities

https://api.stripe.com/

Summary of Resource URL Patterns/v1/charges/v1/charges/{CHARGE_ID}/v1/coupons/v1/coupons/{COUPON_ID}/v1/customers/v1/customers/{CUSTOMER_ID}

21

Versions

/2010-04-01/Accounts/

Twilio

/services/data/v29.0/sobjects/Account

Salesforce

/v2/users

Foursquare

22

Query parameters

/1.1/search/tweets.json?q=%23superbowl &result_type=recent

Twitter

23

Header parameters

24

Conveniences

/me

Facebook

/v1/people/~LinkedIn

/v2/checkins/recentFoursquare

25

Formats

/users/3207.json

SoundCloud/users/3207

26

Formats

27

Actions

/search?q=watermelon&type=post

Facebook

/convert?from=EUR&to=CNY&amount=100

Hypothetical

/droplets/{droplet_id}/reboot

DigitalOcean

28

Authentication

29

Dates

"created_at": "Thu Nov 03 05:19:38 +0000 2011"

Twitter

"DateTime": "2011-10-29T09:35:00Z"

Bing

"createdAt": 1320296464Foursquare

30

Filters

/me?fields=name,birthday,photos.limit(10).fields(id,picture),videos.type(tagged).limit(10).fields(id, source)

Facebook

31

Pagination

offset, limit

Facebook

page, rppTwitter

start, countLinkedIn

32

Pagination

offset, limit

Facebook

33

HATEOAS and the Hypermedia Constraint

34

Hypermedia

35

Great moments in mishandled error code history

36

Errors

37

SDKs

38

Perfect is the enemy of done

39

Questions

rv@apigee.com, @ResourceVerb

brian@apigee.com, @landlessness

marsh@apigee.com, @earth2marsh

Marsh Gardiner, @earth2marsh

Brian Mulloy, @landlessness

Thank you