My fifth grade teacher had a number of common sayings that have stuck with me, but one particularly sticks out in my mind.

There are two ways to learn a hard lesson. You can either learn by experience, or you can watch your friend jump off the bridge and get hurt and decide to not jump off the bridge yourself. Some people just need to learn for themselves.

I have frequently made the mistake of ignoring conventional wisdom only to later discover that the conventions were there for a very good reason. Having learned my lesson by experience, I decided to spend a considerable amount of time reading and thinking about API design in an effort to learn from the earned wisdom of others.

Series Overview

There aren't many resources on API design that are both comprehensive and approachable. Not to say that there are no resources. There are in fact many incredible resources available. But if you are a dummy like me, you might appreciate a more approachable guide.

My original intention was to put out a single article. But, as I have been writing and studying, I realized that it would be much easier to digest (and write) if I split it up into a series of articles.

• HTTP Fundamentals covers the basics of HTTP.
• Design Principles discusses some of the core principles of API design.
• The Anatomy of an API takes a look at the various layers of an API and how they fit together.
• Design and Implementation dives into the details of how to design and implement an API.
• Security and Safety covers the security principles, threat models, and safeguards needed to protect your APIs and the data they handle.
• Testing and Quality covers the various testing strategies and techniques for ensuring the quality of an API.
• Documentation and UX discusses how to create API documentation and developer experiences that speed onboarding and reduce support burden.
• Advanced Topics covers some of the more advanced topics in API design such as versioning.

Some notes before we get started

I contacted a fair number of people who have worked on APIs at scale and asked them if they had any suggested readings or resources. Several were kind enough to share their thoughts and resources. I will include primary sources as well as my own distillation of the key points.

I will be providing some code snippets in the series. These snippets are intended to be illustrative and are not exhaustive or executable.

This series will be a dense collection of information. I have done my best to make things approachable, which will ultimately result in inaccuracies. Verify the information for yourself.

I consider this series to be a work in progress. I will be updating it as I learn more and as I receive feedback. Please feel free to correct me!

With that, let's get started with HTTP Fundamentals.