From df6314ca3d3a84770cfa8aebd8ffb2a47be55ec0 Mon Sep 17 00:00:00 2001 From: John Gatward Date: Wed, 4 Mar 2026 11:40:24 +0000 Subject: [PATCH] Add chapter 1 for design apis --- .../api_design_patterns/part1/chapter1.md | 75 +++++++++++++++++++ .../index.md | 3 - mkdocs.yml | 13 ++-- 3 files changed, 83 insertions(+), 8 deletions(-) create mode 100644 docs/books/api_design_patterns/part1/chapter1.md delete mode 100644 docs/books/structure_and_interpretation_of_computer_programs/index.md diff --git a/docs/books/api_design_patterns/part1/chapter1.md b/docs/books/api_design_patterns/part1/chapter1.md new file mode 100644 index 0000000..272241c --- /dev/null +++ b/docs/books/api_design_patterns/part1/chapter1.md @@ -0,0 +1,75 @@ +# Introduction to APIs + +**API**: **A**pplication **P**rogramming **I**nterface + +## What are web APIs? + +- An API defines the way in which computer systems interact. +- We can find APIs in the standard libraries +- But a special type of API that is built to be exposed over a network and used remotely, "web APIs". +- Those building the API have so much control where as the users have relatively little. +- Web APIs allow you to expose *functionality* without exposing the *implementation*. + - Sometimes they allow users to take advantage of massive compute. + +## What are resource-oriented APIs? + +- Many web APIs act like servants. + - You ask them to do something, and they go off and do it. +- This is called *remote procedure call* (**RPC**) + +### So why aren't all APIs RPC-orinented? + +One of the main reasons is the idea of *statefulness*. + +> **Stateless**: When an API call can be made independently from all other API requests, with no additional context. +> **Statefulness**: A web API that stores context on a user from previous API requests. +> For example a web API that stores a user's favourite cities and provides weather forecasts for just those has no runtime inputs but requires a state to be set by the user. + +Consider the following API method names: +1. `ScheduleFlight()` +2. `GetFlightDetails()` +3. `ShowAllFlights()` +4. `CancelReservation()` +5. `RescheduleFlight()` +6. `UpgradeTrip()` + +- Each one of these RPCs is pretty descriptive, but we have to memorize these methods, each of which is subtly different. + - e.g. sometimes we talk about flight, other times we talk about a trip or a reservation. +- We also need to memorise which action is used in the method. + - Was it `ShowFlights()`, `ShowAllFlights()`, `ListFlights()` etc + +We need to standardise, by providing a standard set of building blocks - method-resource +1. `CreateFlightReservation()` +2. `GetFlightReservation()` +3. `ListFlightReservation()` +4. `DeleteFlightReservation()` +5. `UpdateFlightReservation()` + +- Resource-oriented APIs will be much easier for users to learn, understand and remember. + - Standardisation makes it easy to combine what you already know (set of standard actions) which the resource which is easy to learn. + +## What makes an API "good"? + +What is the purpose of building an API in the first place? +1. We have some functionality that some users want. +2. Those users want to use this functionality programmatically + +### Operational + +- The system as a whole must be operational. + - It must do the thing users actually want. +- **Non-operational** requirements: It must perform how the user expects. + - e.g. like latency + +### Expressive + +- The system needs to allow users to express the thing they want to do *clearly* and *simply*. +- The API should be designed such that there is a clear and simple way to do so. +- Avoid work arounds - if there is some functionality a user wants but there is not an easy way to do this, this is called a *workaround*. + - e.g. If you have a translation API, users can create a detect language feature by constantly pinging translate endpoint. + +### Simple + +- We could think of simplicity as the number of endpoints. + - However an API that relies on a single `ExecuteAction()` method just shifts complexity from one place to another. +- APIs should aim to expose the functionality users want in the most straightforward way possible, making the API as simple as possible, but no simpler. diff --git a/docs/books/structure_and_interpretation_of_computer_programs/index.md b/docs/books/structure_and_interpretation_of_computer_programs/index.md deleted file mode 100644 index 3463b16..0000000 --- a/docs/books/structure_and_interpretation_of_computer_programs/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Structure and Interpretation of Computer Programs - -We are about to study the idea of a *computational process*. Computational processes are abstract beings that inhabit computers. As they evolve, processes manipulate other abstract things called data. The evolution of a process is directed by a pattern of rules called a *program*. People create programs to direct processes. In effect, we conjure the spirits of the computer with our spells. diff --git a/mkdocs.yml b/mkdocs.yml index 37dc9dd..fc5c0b8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,9 +60,12 @@ nav: - Home: index.md - Books: - Designing Data-Intensive Applications: - - Preface: books/designing_data_intensive_applications/preface/index.md - - Part 1. Foundations of Data Systems: - - Chapter 1. Reliable, Scalable and Maintainable Applications: books/designing_data_intensive_applications/part1/chapter1.md - - Chapter 2. Data Models and Query Languages: books/designing_data_intensive_applications/part1/chapter2.md - - Structure and Interpretation of Computer Programs: books/structure_and_interpretation_of_computer_programs/index.md + - Preface: books/designing_data_intensive_applications/preface/index.md + - Part 1. Foundations of Data Systems: + - Chapter 1. Reliable, Scalable and Maintainable Applications: books/designing_data_intensive_applications/part1/chapter1.md + - Chapter 2. Data Models and Query Languages: books/designing_data_intensive_applications/part1/chapter2.md + - API Design Patterns: + - Part 1. Introduction: + - Chapter 1. Introduction to APIs: books/api_design_patterns/part1/chapter1.md +