diff --git a/.gitea/workflows/deploy.yaml b/.gitea/workflows/deploy.yaml new file mode 100644 index 0000000..7ccfad8 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..da69810 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +site/ +venv +.venv diff --git a/README.md b/README.md new file mode 100644 index 0000000..acbbe8a --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# Notes + +A repository to store the notes taken. diff --git a/ci/mkdocs/Dockerfile b/ci/mkdocs/Dockerfile new file mode 100644 index 0000000..283beab --- /dev/null +++ b/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 diff --git a/ci/mkdocs/requirements.txt b/ci/mkdocs/requirements.txt new file mode 100644 index 0000000..fa74f65 --- /dev/null +++ b/ci/mkdocs/requirements.txt @@ -0,0 +1,3 @@ +mkdocs==1.6.1 +mkdocs-material==9.7.3 +pymdown-extensions==10.21 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..c25e96a --- /dev/null +++ b/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. 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..c82ebe3 100644 --- a/mkdocs.yml +++ b/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 +