Add chapter 1 for design apis

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.

docs/books/structure_and_interpretation_of_computer_programs/index.md

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

mkdocs.yml

@@ -64,5 +64,8 @@ nav:
       - 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
+    - API Design Patterns:
+      - Part 1. Introduction:
+        - Chapter 1. Introduction to APIs: books/api_design_patterns/part1/chapter1.md
+