✨ (Section 3) Add section 3, first REST API, and project

.templates/lecture.md

@@ -10,18 +10,8 @@ description: A brief description of the lecture goes here.
 - [ ] Write TL;DR
 - [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
 
-- [Lecture Title](#lecture-title)
-  - [In this video... (TL;DR)](#in-this-video-tldr)
-  - [Code at the start of this lecture](#code-at-the-start-of-this-lecture)
-  - [Code written in this lecture](#code-written-in-this-lecture)
-  - [Final code at the end of this lecture](#final-code-at-the-end-of-this-lecture)
 
-# Lecture Title
-
-## In this video... (TL;DR)
 
-## Code at the start of this lecture
+# Lecture Title
 
-## Code written in this lecture
 
-## Final code at the end of this lecture

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# How to contribute to this course
+
+## E-book contributions
+
+### How to run the e-book
+
+Clone the repo and navigate to the `docs` folder.
+
+There, run:
+
+```
+npm install
+```
+
+Then you can run the e-book with:
+
+```
+npm run start
+```
+
+If you make any changes to the e-book, please keep changes as simple as possible and create a PR with your changes into the `develop` branch.
+
+If you are making larger changes, please create a Discussion first and let's talk about it!
+
+### Making changes to projects
+
+All the finished projects that we cover in the course are in the `projects` folder. Making changes to these projects is done very carefully, especially after recording.
+
+Please start a Discussion before making any changes, as doing so can make the experience for students confusing (if the videos and e-book are different).

docs/docs/03_first_rest_api/01_project_overview/README.md

@@ -0,0 +1,111 @@
+---
+title: Project Overview
+description: A first look at the project we'll build in this section.
+---
+
+# Overview of your first REST API
+
+In this section we'll make a simple REST API that allows us to:
+
+- Create stores, each with a `name` and a list of stocked `items`.
+- Create an item within a store, each with a `name` and a `price`.
+- Retrieve a list of all stores and their items.
+- Given its `name`, retrieve an individual store and all its items.
+- Given a store `name`, retrieve only a list of item within it.
+
+This is how the interaction will go!
+
+## Create stores
+
+Request:
+
+```
+POST /store {"name": "My Store"}
+```
+
+Response:
+
+```
+{"name": "My Store", "items": []}
+```
+
+## Create items
+
+Request:
+
+```
+POST /store/My Store/item {"name": "Chair", "price": 175.50}
+```
+
+Response:
+
+```
+{"name": "Chair", "price": 175.50}
+```
+
+## Retrieve all stores and their items
+
+Request:
+
+```
+GET /store
+```
+
+Response:
+
+```
+{
+    "stores": [
+        {
+            "name": "My Store",
+            "items": [
+                {
+                    "name": "Chair",
+                    "price": 175.50
+                }
+            ]
+        }
+    ]
+}
+```
+
+## Get a particular store
+
+Request:
+
+```
+GET /store/My Store
+```
+
+Response:
+
+```
+{
+    "name": "My Store",
+    "items": [
+        {
+            "name": "Chair",
+            "price": 175.50
+        }
+    ]
+}
+```
+
+## Get only items in a store
+
+Request:
+
+```
+GET /store/My Store/item
+```
+
+Response:
+
+```
+[
+    {
+        "name": "Chair",
+        "price": 175.50
+    }
+]
+```

docs/docs/03_first_rest_api/02_getting_set_up/README.md

@@ -0,0 +1,36 @@
+---
+title: Getting set up
+description: Set up a Flask project and create the Flask app.
+---
+
+# Getting set up
+
+Create a virtual environment and activate it.
+
+```
+python3.10 -m venv .venv
+source .venv/bin/activate
+```
+
+Install Flask.
+
+```
+pip install flask
+```
+
+Create a file for the Flask app (I like to call it `app.py`)
+Create the Flask app.
+
+```py title="app.py"
+from flask import Flask
+
+app = Flask(__name__)
+```
+
+Now you can run this app using the Flask Command-Line Interface (CLI):
+
+```
+flask run
+```
+
+But the app doesn't do anything yet! Let's work on our first API endpoint next.

docs/docs/03_first_rest_api/03_first_rest_api_endpoint/README.md

@@ -0,0 +1,44 @@
+---
+title: Your First REST API Endpoint
+description: Learn how to define a REST API endpoint using Flask.
+---
+
+# Your First REST API Endpoint
+
+Let's start off by defining where we'll store our data. In most REST APIs, you'd store your data in a database. For now, and for simplicity, we'll store it in a Python list.
+
+Later on we'll work on making this data dynamic. For now let's use some sample data.
+
+```py title="app.py"
+from flask import Flask
+
+app = Flask(__name__)
+
+stores = [{"name": "My Store", "items": [{"name": "my item", "price": 15.99}]}]
+```
+
+Now that we've got the data stored, we can go ahead and make a Flask route that, when accessed, will return all our data.
+
+```py title="app.py"
+from flask import Flask
+
+app = Flask(__name__)
+
+stores = [{"name": "My Store", "items": [{"name": "my item", "price": 15.99}]}]
+
+
+@app.get("/store")
+def get_stores():
+    return {"stores": stores}
+```
+
+## Anatomy of a Flask route
+
+There are two parts to a Flask route:
+
+- The endpoint decorator
+- The function that should run
+
+The endpoint decorator (`@app.get("/store")`) _registers_ the route's endpoint with Flask. That's the `/store` bit. That way, the Flask app knows that when it receives a request for `/store`, it should run the function.
+
+The function's job is to do everything that it should, and at the end return _something_. In most REST APIs, we return JSON, but you can return anything that can be represented as text (e.g. XML, HTML, YAML, plain text, or almost anything else).

docs/docs/03_first_rest_api/04_what_is_json/README.md

@@ -0,0 +1,71 @@
+---
+title: "What is JSON?"
+description: JSON is the way we normally transfer data to and from REST APIs.
+---
+
+# What is JSON?
+
+JSON is just a (usually long) string whose contents follow a specific format.
+
+One example of JSON:
+
+```json
+{
+    "key": "value",
+    "another": 25,
+    "listic_data": [
+        1,
+        3,
+        7
+    ],
+    "sub_objects": {
+        "name": "Rolf",
+        "age": 25
+    }
+}
+```
+
+So at its core, you've got:
+
+- Strings
+- Numbers
+- Booleans (`true` or `false`)
+- Lists
+- Objects (akin to dictionaries in Python)
+  - Note that objects are not ordered, so the keys could come back in any order. This is not a problem!
+
+At the top level of a piece of JSON you can have an object or a list. So this is also valid JSON:
+
+```json
+[
+    {
+        "name": "Rolf",
+        "age": 25
+    },
+    {
+        "name": "Anne",
+        "age": 27
+    },
+    {
+        "name": "Adam",
+        "age": 23
+    }
+]
+```
+
+When we return a Python dictionary in a Flask route, Flask automatically turns it into JSON for us, so we don't have to.
+
+Remember that "turning it into JSON" means two things:
+
+1. Change Python keywords and values so they match the JSON standard (e.g. `True` to `true`).
+2. Turn the whole thing into a single string that our API can return.
+
+:::tip
+Note that JSON can be "prettified" (as the above examples), although usually it is returned by our API "not-prettified":
+
+```json
+[{"name":"Rolf","age":25},{"name":"Anne","age":27},{"name":"Adam","age":23}]
+```
+
+This removal of newlines and spaces, believe it or not, adds up and can save a lot of bandwidth since there is less data to transfer between the API server and the client.
+:::