Kirsten Hunter - Irresistible APIs: Designing web APIs that developers will love

For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity. For more information, please contact

Special Sales Department Manning Publications Co. 20 Baldwin Road PO Box 761 Shelter Island, NY 11964 Email: orders@manning.com

2017 by Manning Publications Co. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps.

Recognizing the importance of preserving what has been written, it is Mannings policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end. Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine.

Manning Publications Co.20 Baldwin RoadPO Box 761Shelter Island, NY 11964

Development editor: Lesley TritesTechnical development editor: Nick WattsCopyeditor: Elizabeth WelchProofreader: Corbin CollinsTechnical proofreader: David Fombella PombalTypesetter: Dottie MarsicoIllustrator: Viseslav RadovicCover designer: Leslie Haimes

ISBN 9781617292552

Printed in the United States of America

1 2 3 4 5 6 7 8 9 10 EBM 21 20 19 18 17 16

Building an irresistible API doesnt only make good business senseit also makes developers happy and productive rather than grumpy and frustrated. Im very happy to see Kirsten write this book, which explains how to build well-engineered APIs and explores what makes a developer actively want to use that API.

Ill begin with a story. Its September 2008, and Netflix is running a hack day. This is a day on which anyone at Netflix can build anything they want. It starts at noon one day and finishes at noon the next. You can work through the night if you need to. The Netflix API team was about to release the initial version of a public API for Netflix and had scheduled the hack day as a way to get extra testing time before the release. The Apple iPhone had been released earlier that year, and the first software developer toolkit for the iPhone had been released that summer. I was a manager at Netflix at that time, but I had started to build an iPhone app in my spare time and decided to build the first ever Netflix mobile app for the hack day.

The odds werent looking good. I barely knew the Objective-C language that iPhone apps are written in, and no one else at Netflix had ever used it. The authentication protocol was new and buggy, and I had to improvise some iPhone code to connect to Netflix. I recruited an engineer to help. We spent several hours understanding and debugging the OAuth security protocol. Finally, I got the iPhone to connect successfully and started trying to make sense of the responses from API queries. The API was based on an XML-based standard called AtomPub, and generating the requests was awkward. Parsing them was even more awkward. It was really intended to be used from a web browser, not to support a mobile app. After a late night of coding and a lot of grumbling, I finally had a working prototype. In the afternoon, we all showed our hacks to a panel of judges, and I won a prize. I put it on the App Store, and it was the first public Netflix mobile app. It wasnt until 2010 that Netflix released official iPad and iPhone apps.

Netflix created a developer program around the public API, and Kirsten was one of the engineers hired to help run the program. In 2010 we both attended an iPad Dev Camp, run like an extended public hack day, and worked together on a Netflix-related iPad app. We were using the Netflix API despite its shortcomings, and I think there was a missed opportunity. Ultimately, the public API was a failure for Netflix, and the company shut it down. Kirsten tells the rest of this story in of this book.

I learned a lot from this experienceand from Kirsten herself. In 2016 this is a very important topic. Many companies need an API to do business. Many are even actively competing with other companies that have alternative APIs. In the past, software products were bought as prebuilt packages and were hand configured. Today software is often chosen by rummaging around on GitHub, trying to figure out which project has the most developer traction, and installation and deployment is automated via APIs. The lack of friction in web service and open sourcebased business models is there to be exploited by the viral spread of irresistible APIs.

Thank you, Kirsten, for this contribution to making the world a better place.

A DRIAN C OCKCROFT T ECHNOLOGY F ELLOW AT B ATTERY V ENTURES

From the time I started working with REST APIs at Socialtext in 2005, Ive been fascinated by web services platforms. At Socialtext, we created a solid, consistent REST API, but it was only truly usable by our own team because the developer experience was immature. The documentation didnt have great tutorials, and our outreach was limited. I learned to love the idea of a platform built on a solid protocol like HTTP and the extensibility of REST APIs.

Ever since getting struck by the bug, Ive been an enthusiastic advocate for the design and usability of web APIs. Ive spent many a weekend creating mashups with Twitter, Facebook, Freebase (RIP), LinkedIn, Netflix, and tens of other web services. As I used these APIs, I started to develop an overall definition for platforms with irresistible APIsplatforms that offered amazing developer experiences. I came to realize that an irresistible API needs more than excellent, consistent interfaces. Its hard to succeed without great documentation, fantastic sample code, and an enthusiastic support structure.

As I worked in the industry, I was repeatedly employed in great positions to support developers and understand their needs. I came to realize that great developers who are trying to implement integrations with APIs dont automatically understand web services, so I integrated this information into my ideas about irresistible APIs: dont make assumptions about what your developers know. I started speaking at conferences and writing articles to help client developers understand and create amazing applications using web APIs.

I realized that educating the API creators was a more efficient way to improve the industry, and I began by speaking at the API Strategy and Practice conferences about developer experience to the companies developing and providing APIs. I started meeting and brainstorming with individuals in the API industry about best practices for web APIs. Over time I worked on ideas around creating APIs: treating your API as a first-class product, rather than shunting it off to the side of your main application. Despite the importance and visibility of web services, many companies hadnt given any thought to designing for use cases and business value.