DELETE /ivory-tower

Changing the way APIs are developed

Transcript

1. 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.
2. 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.
3. ...BUT THEN... Monday, November 19, 12 We wanted to control things. XML-RPC & SOAP emerged (because XML was way to go in ‘00s).
4. 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.
5. OPPA REST-STYLE Monday, November 19, 12 REST appeared. No spec, no protocol — just philosophy. Few things right: exposing protocol,
6. PROPHECY Monday, November 19, 12 That is a bit of a problem. It is a holy paper written by a prophet with details omitted
7. DISCIPLES Monday, November 19, 12 ...and prophet had many disciples. Sometimes, they don’t get along well. But still — they are the default now .
8. 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.
9. 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?
10. 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.
11. 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.
12. OH, *THOSE* EXAMPLES Monday, November 19, 12 Documentation is rarely brought up-to-date with reality and deteriorates -- *especially* payload examples. Regression happens.
13. 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.
14. 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)?
15. SOFTWARE SOLUTIONS Monday, November 19, 12 How to solve this? Apply solutions you already know — the ones from software world.
16. 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.
17. ACTS OF BALANCE Monday, November 19, 12 Evolution & iteration vs. backward compatibility
18. TEST AS USUAL Monday, November 19, 12 Integration testing — and especially regression testing — ALL the time.
19. 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.
20. Consumers (developers) Provider (developer) DEVELOPERS—DEVELOPERS Monday, November 19, 12 There are developers on both sides. Leverage that.
21. 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!
22. 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.
23. NEAT DOCUMENTATION Monday, November 19, 12 Nice documentation, for free. We are doing what sphinx & RTD did for Python docs.
24. WHO FAILED ME? Monday, November 19, 12 Run against real server. Look for diffs.
25. 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.
26. 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.
27. Q&A Monday, November 19, 12
28. 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