Slide 1

Slide 1 text

Lukas Linhart Bee, Apiary.io DELETE /ivory-tower Monday, November 19, 12 Good (early) morning, everyone. How APIs are done today and how they should be done. Oh God, please do not let us live with *those* APIs again.

Slide 2

Slide 2 text

FIRST (WEB) API Monday, November 19, 12 What is the first API you can think of? It was actually not so bad. CSV-on-a-server! RESTful before it was cool.

Slide 3

Slide 3 text

...BUT THEN... Monday, November 19, 12 We wanted to control things. XML-RPC & SOAP emerged (because XML was way to go in ‘00s).

Slide 4

Slide 4 text

BIGGEST FALLACY Monday, November 19, 12 We tried to abstract away the only thing that is not going to be any better — latency They were also too close to the languages, therefore interfering with things_like namingConventions.

Slide 5

Slide 5 text

OPPA REST-STYLE Monday, November 19, 12 REST appeared. No spec, no protocol — just philosophy. Few things right: exposing protocol,

Slide 6

Slide 6 text

PROPHECY Monday, November 19, 12 That is a bit of a problem. It is a holy paper written by a prophet with details omitted

Slide 7

Slide 7 text

DISCIPLES Monday, November 19, 12 ...and prophet had many disciples. Sometimes, they don’t get along well. But still — they are the default now .

Slide 8

Slide 8 text

FUTURE Monday, November 19, 12 Very bleeding-edge frontier is moving beyond REST. Realtime/server push APIs are open problem, as well as XMPP-like ones. Let’s not talk about them yet. REST is now mainstream and we don’t have it covered yet.

Slide 9

Slide 9 text

WHAT HAS BEEN SEEN... Monday, November 19, 12 But anyways — we saw a lot of REST APIs and a hell lot of them were horrible and didn’t deliver their promise. So, why? And how to avoid it?

Slide 10

Slide 10 text

IVORY TOWER OF API Monday, November 19, 12 Design by server committee. Provider is locked in their view of the world, not communicating with consumer.

Slide 11

Slide 11 text

EXPOSED INTERNALS Monday, November 19, 12 While doing it, we also model around his view of the world and his “atomic, normalized particles”. All those ORM-to-API frameworks. Data/model-centric, not use-case centric.

Slide 12

Slide 12 text

OH, *THOSE* EXAMPLES Monday, November 19, 12 Documentation is rarely brought up-to-date with reality and deteriorates -- *especially* payload examples. Regression happens.

Slide 13

Slide 13 text

AS THE TIME GOES BY Monday, November 19, 12 API evolution is also a problem — resource change management and deprecation, but also payload evolution. BTW, XML did this right. Versioned namespaces are neat solution, now transplanted using versioned suffixes in Content-Types.

Slide 14

Slide 14 text

LOOKING FOR PROBLEMS Monday, November 19, 12 ...and, when documentation failed them — how do developers look for solutions? How to they report bugs and problems? And, are they not being bounced by 1st level user support (have you tried to turn your API client off and on)?

Slide 15

Slide 15 text

SOFTWARE SOLUTIONS Monday, November 19, 12 How to solve this? Apply solutions you already know — the ones from software world.

Slide 16

Slide 16 text

PROTOTYPE & ITERATE Monday, November 19, 12 Build data prototypes earlier then the full thing. Verify it fulfills consumer use-case. Alter for them again. This doesn’t mean you have to deploy publicly. Feature-flip as usual.

Slide 17

Slide 17 text

ACTS OF BALANCE Monday, November 19, 12 Evolution & iteration vs. backward compatibility

Slide 18

Slide 18 text

TEST AS USUAL Monday, November 19, 12 Integration testing — and especially regression testing — ALL the time.

Slide 19

Slide 19 text

DECOUPLE ALL THE THINGS Monday, November 19, 12 Try to be at least a bit future-proof. No exposing of your internal structures — they WILL change. Concentrate on use-cases.

Slide 20

Slide 20 text

Consumers (developers) Provider (developer) DEVELOPERS—DEVELOPERS Monday, November 19, 12 There are developers on both sides. Leverage that.

Slide 21

Slide 21 text

APPROACH WE BELIEVE IN Monday, November 19, 12 We believe in this development style, this is why we have build product with those things in mind. So now — demo time!

Slide 22

Slide 22 text

OUR LANGUAGE HOST: http://api.twitter.com/ --- Twitter API 3.0 --- --- Welcome to our API. Comments support Markdown syntax --- -- Retrieve Tweets -- GET /tweets > Accept: application/json < 200 < Content-Type: application/json { "items": [ { "url": "/feed", "range":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 } ] } Monday, November 19, 12 Developed in simple DSL. Versioned along the software. Docs and tests generated from that. Oh, and the language and parser are open-sourced.

Slide 23

Slide 23 text

NEAT DOCUMENTATION Monday, November 19, 12 Nice documentation, for free. We are doing what sphinx & RTD did for Python docs.

Slide 24

Slide 24 text

WHO FAILED ME? Monday, November 19, 12 Run against real server. Look for diffs.

Slide 25

Slide 25 text

FACT OF LIFE Monday, November 19, 12 It’s part of our workflow. Blueprint is in our github repo. We can branch, diff, fork & pull.

Slide 26

Slide 26 text

EMBRACE COMMUNITY Monday, November 19, 12 API structure should be open-source. Let your client send improvements. Embrace enthusiastic clients. Rejoice. We are the GitHub for APIs.

Slide 27

Slide 27 text

Q&A Monday, November 19, 12

Slide 28

Slide 28 text

CREDITS (THANKS!) • http://www.flickr.com/photos/41454560@N04/3945245093/ • http://www.flickr.com/photos/24409978@N00/1663375474/ • http://www.flickr.com/photos/34547181@N00/4203903017/ • http://www.flickr.com/photos/21369563@N00/2053892004/ • http://www.flickr.com/photos/mamjodh/2298073734/sizes/o/in/photostream/ • http://www.flickr.com/photos/90463792@N00/139154974/ • http://www.flickr.com/photos/78147607@N00/438985771/ • http://www.flickr.com/photos/vinothchandar/5793059580/sizes/l/in/photostream/ • http://www.flickr.com/photos/68089229@N06/6269439597/ • http://www.flickr.com/photos/31509147@N00/6713582723/ • http://www.flickr.com/photos/75389315@N00/6036322005/ • http://www.flickr.com/photos/39781580@N04/4114328660/ • http://www.flickr.com/photos/9887700@N08/4153993295/ • http://www.flickr.com/photos/36579587@N05/7804846882/ • http://www.flickr.com/photos/16230215@N08/2864168894/ • http://www.flickr.com/photos/34120957@N04/4199675334/ • http://www.flickr.com/photos/28548387@N00/556656621/ • http://www.flickr.com/photos/88996417@N00/427383721/ • http://www.flickr.com/photos/8070463@N03/5597937879/ • http://www.flickr.com/photos/10101046@N06/3574375600/ • Monday, November 19, 12