Add api design chapter 1

.gitea/workflows/deploy.yaml

@@ -0,0 +1,44 @@
+name: Build and Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Important for switching branches
+
+      - name: Build and Extract Site
+        run: |
+          docker build -t mkdocs-temp -f ci/mkdocs/Dockerfile .
+          docker create --name temp-container mkdocs-temp
+          # Copying content to a folder named 'output_content' to avoid naming collisions
+          docker cp temp-container:/build/site ./output_content
+          docker rm temp-container
+
+      - name: Deploy to docs-static Branch
+        run: |
+          git config user.name "gitea-actions[bot]"
+          git config user.email "actions@noreply.gitea.io"
+          
+          # Increase buffer to handle larger media files
+          git config http.postBuffer 524288000
+
+          mv output_content /tmp/site_final
+          git checkout --orphan docs-static
+          git rm -rf .
+          cp -r /tmp/site_final/. .
+
+          # Optional: Remove source maps to save space
+          find . -name "*.map" -type f -delete
+
+          git add .
+          git commit -m "Automated MkDocs build"
+          git push origin docs-static --force

.gitignore

@@ -0,0 +1,3 @@
+site/
+venv
+.venv

README.md

@@ -0,0 +1,3 @@
+# Notes
+
+A repository to store the notes taken.

ci/mkdocs/Dockerfile

@@ -0,0 +1,9 @@
+FROM ghcr.io/squidfunk/mkdocs-material:latest
+
+WORKDIR /build
+
+COPY . .
+
+RUN pip install --no-cache-dir mkdocs-minify-plugin
+
+RUN mkdocs build

ci/mkdocs/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs==1.6.1
+mkdocs-material==9.7.3
+pymdown-extensions==10.21

docs/books/api_design_patterns/part1/chapter1.md

@@ -0,0 +1,80 @@
+# Introduction to APIs
+
+**API**: Application Programming Interface
+
+## 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. 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 workarounds - 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

@@ -25,6 +25,8 @@ theme:
     - search.suggest
     - search.highlight
     - search.share
+    - content.action.edit
+    - content.action.view
 
 markdown_extensions:
   - admonition
@@ -60,9 +62,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
+