Joshua S. Ponelat - Designing APIs with Swagger and OpenAPI

Joshua S. Ponelat, Lukas L. Rosenstock

Foreword by Tony Tam

To comment go to liveBook

Manning

Shelter Island

For more information on this and other Manning titles go to

www.manning.com

For online information and ordering of these and other Manning books, please visit www.manning.com. The publisher offers discounts on these books 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

2022 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.

ISBN: 9781617296284

To Tony, Ron, and Ciaran for shaping my current career

Josh

To everyone who promised theyd buy one, even before it was done

Lukas

The job of a software developer has changed dramatically in the last decade. Advanced features like single sign-on, persistence, synchronization across devices, and sharing have become standardized and accepted as commonplace. To the small shop, developing these necessary features is often more work than building the application itself.

REST APIs opened the door for developers to build applications with greater focus on their core values and less on incidental features. Initially, it was up to each provider to create bespoke documentation and client libraries. Swagger and OpenAPI were born to establish a common language to describe REST APIs and make consuming and producing these APIs quicker and more effective.

In this book, Josh and Lukas take a holistic approach to teaching API design and implementation. Using interesting and relevant examples, they first teach the reader how to document an existing API with OpenAPI literacy. Then, they expand that core knowledge to introduce design-first techniques. OpenAPI wouldnt be the same without the awesome tools and open source software that make it so easy to use, and this book explores some powerful ones that will help readers design, build, share, and investigate all sorts of REST APIs.

As applications become more complex and end users continue to expect established features, it is inevitable that the reliance on OpenAPI and other spec-based standards will increase. This book clearly presents patterns and techniques that will enhance the experience for all software developers who need to work with APIs.

Tony Tam, Founder of Swagger and helping drive innovation at Apple iCloud

Im Josh. I want to teach people. Always have, really.

Swagger and OpenAPI are areas that Ive come to feel shouldnt be all that complicated. Yet I saw many folks who wrestled unnecessarily with the topicsfolks who needed to make decisions that would affect many others. It was hard to watch, and I sympathized. When I joined Swagger in 2015 (then, shortly after, SmartBear), I had never heard of YAML and had no idea how writing it in a certain way would help with APIs. It was all a murky blend of ideas, jargon, and an eclectic collection of tools. It took some time to unwind that in my head, and its that journey that led me here.

After writing one third of this book, I started feeling burnt out, as Im sure many authors do. I was working full time on SwaggerHub and in the gaps was writing about the same topic: OpenAPI. When Lukas agreed to help coauthor this book, he not only brought great ideas and support, but also whole new angles from which to view OpenAPI. Its been great to share this journey with him.

Im Lukas. Just like Josh, I enjoy teaching and explaining stuff. Being asked to take part in the creation of a book on a topic (APIs) that Im very passionate about and that has been a common thread in my diverse set of work for so long, has been a great honor.

What weve both learned is that writing is hard. Its hard because our heads are full of unconnected ideas and thoughts. Writing them down forces us to find clarity. And even if were confident in short-form technical writing, such as tutorials and blog posts, tackling a full-length book is a whole different beast. It requires us to find a common narrative structure to present diverse aspects of the subject in a way that helps readers understand and follow along. Doing this as a team requires not just clarity in our own heads but also strong collaboration.

Unsurprisingly, designing APIs is much like writing. Creating a quick API to hook up two different systems isnt a big deal. Building a strong foundation that both makes the API work and ensures that it is well documented, easy to understand, maintainable, and extensible is a challenge. Also, like coauthoring a book or building a software project, designing APIs is a team sport. Our goal is to tackle this challenge together with you.

When it comes to designing new APIs and describing old ones, we want your work to have the impact you desire on the world and your life. We hope that this book will help you ever so slightly in achieving those goals.

Wed like to thank the open source community for all the hard work they have put into Swagger and OpenAPI. Without this great community, we wouldnt have this fun topic to write about.

We thank our editor, Jenny Stout, as well as the rest of the team at Manning, and all those involved in the process of making this book: without you all, this book would be an erratic collection of chaotic thoughts and scribbles.