DESIGNING WEB APIS EBOOK
HOW THIS BOOK IS ORGANIZED
This book comprises three major parts:
Theory (Chapters 1–4)
Here we cover the basic concepts of building an API, review different API patterns, and discuss different aspects of a good API.
Practice (Chapters 5–7)
In these chapters, we talk about how to actually design an API and manage its operation in production.
Developer Love (Chapters 8–11)
In this section, we go beyond designing an API and show you how to build a thriving developer ecosystem around your API.
Also included in this book are case studies (lessons from Stripe, Slack, Twitch, Microsoft, Uber, GitHub, Facebook, Cloudinary, Ora‐ cle, and more!), advice and pro tips from experts in the field, and stories about real-life experiences. In Appendix A, you’ll find some handy worksheets, templates, and checklists.
OVERVIEW OF APIS
Building a popular developer platform with an API that is used by millions of developers is one of the most challenging and exciting endeavors you can undertake in your software career. In this book, you’ll learn how to do that.
APIs are at the core of modern software development. They tackle a basic developer challenge: how can I, as a software engineer, expose the code I’ve written to other developers to use and innovate with? Building software in the modern world is very much like building with LEGO bricks. As a developer you have access to a vast set of APIs that expose services such as payments, communication, authorization and authentication, and so forth. When building new software, your job as a software engineer is to use these APIs to compose your new product, reusing code that others built in order to save time and avoid reinventing the wheel.
Many software engineers who enjoyed playing with LEGOs as kids still love to play with them today. And who wouldn’t? It’s fun, and you get to build useful stuff with awesome colorful pieces that connect to one another seamlessly. But what if you could build the LEGO itself? Wouldn’t it be great if you could invent not only new LEGO kits, but also the LEGO parts themselves, and let others innovate with them? When building your own API, you are in effect creating your own LEGO parts for other developers to use.
HISTORY OF APIS
APIs are not a new in computer science, in the ’60s, developers began to build standard libraries for the first procedural languages and share these with other developers. These developers could use the standard functionality of these libraries without knowing their internal code.
Then, in the ’70s and ’80s, with the emergence of network connected computers, came the first network APIs that exposed services developers could consume through Remote Procedure Calls (RPCs). With RPCs, developers could expose their functionality over the network and call remote libraries as if they were local. Programming languages like Java provided further abstraction and complexity, with messaging middleware servers that listed and orchestrated these remote services.
During the ’90s, with the emergence of the internet, many companies wanted to standardize the way we build and expose APIs. Standards such as the Common Object Request Broker Architecture (CORBA), the Component Object Model (COM) and Distributed Component Object Model (DCOM) by Microsoft, and many others sought to become the de facto way to expose services over the web. The problem was that most of these standards were complex to manage, mandated similar programming languages on both sides of the network, and sometimes required the local installation of part of the remote service (commonly called a _stub_) in order to access it. It was a mess; the dream of interoperability soon became a night mare of configurations and constraints.
In the late ’90s and early ’00s came more open and standard ways of accessing remote services over the web (web APIs). First with the Simple Object Access Protocol (SOAP) and Extensible Markup Language (XML), and then with Representative State Transfer (REST) and JavaScript Object Notation (JSON), accessing services became easier and more standardized without dependencies on client-side code or programming language. We cover the more popular and useful of these methods in this book.
One by one, every tech company began exposing useful services through APIs from rom the early days of the Amazon Affiliate API (2002), to the Flickr API (2004), the Google Maps API (2005), and the Yahoo! Pipes API (2007), there are now thousands of APIs exposing every service imaginable, from image manipulation to artificial intelligence. Developers can call these and create new products that are a composition of multiple APIs, just like building with LEGO bricks.
Although APIs have become a commodity and using them an easy task, building an API is still an art form. Do not take this challenge lightly; building a solid API is not easy. APIs should be brilliantly simple and highly interoperable, like with LEGO, each part from any kit should work well with every other piece in any other kit. APIs should also be accompanied by developer programs and resources to help developers adopt them. Building a solid API is just the first step; you also need to create and support a thriving ecosystem of developers. We cover these challenges in the last part of this book.
We wrote this book because we realized that over the course of our careers we had followed similar processes and made similar decisions, processes, and optimizations for many APIs, but these guidelines had not been compiled into a single authoritative resource. We could each point to blog posts or articles here and there about separate topics, but there wasn’t one place that described how to design for the evolution and growth of web APIs and their ecosystems. With this book, we hope to put at your fingertips all the tools that we’ve created and discovered over the course of our careers building APIs. Having access to this skill set is very valuable. It can be the difference between the success and failure of your business or technol‐ ogy, and it can be the unique advantage that will drive your career.
CONCLUSION:
How This Book Is Organized.
This book comprises three major parts: Theory (Chapters 1–4)
Here we cover the basic concepts of building an API, review different API patterns, and discuss different aspects of a good API.
Practice (Chapters 5–7)
In these chapters, we talk about how to actually design an API and manage its operation in production.
Developer Love (Chapters 8–11)
In this section, we go beyond designing an API and show you how to build a thriving developer ecosystem around your API.
Also included in this book are case studies (lessons from Stripe, Slack, Twitch, Microsoft, Uber, GitHub, Facebook, Cloudinary, Ora‐ cle, and more!), advice and pro tips from experts in the field, and stories about real-life experiences. In Appendix A, you’ll find some handy worksheets, templates, and checklists.