Fix: #111. Add gh-pages (#112)

* fix url

* Fix merge keys.

* Throttling middleware.

* Consolidation.

* format yaml

* Security: Availability, Integrity, Confidentiality

* Reorganize CIA. Valid OAS.

* more stuff

Author: ioggstream

connexion-101/.gitignore

@@ -9,3 +9,4 @@ core*
 *_python_intro.ipynb
 .tox
 *generated*
+*deleteme*

connexion-101/034-schema-design.md

@@ -128,7 +128,7 @@ The `$ref` value is an URI.
 components:
   schemas:
     Problem:
-      $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/schemas/Problem'
+      $ref: 'components.oas3.yaml#/components/schemas/Problem'
 ```
 
 > Note: Schema registries guarantee consistency: if a shared schema adds a required field,
@@ -369,7 +369,7 @@ to ensure consistent errors
 components:
   schemas:
     Problem:
-      $ref: 'https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/schemas/Problem'
+      $ref: 'components.oas3.yaml#/components/schemas/Problem'
 ```
 
 ----

connexion-101/040-01-connexion-writing-operationid.md

@@ -149,7 +149,7 @@ components:
 
 ----
 
-Or just `$ref` the `Retry-After` defined in <https://teamdigitale.github.io/openapi/0.0.5/definitions.yaml#/headers/Retry-After>
+Or just `$ref` the `Retry-After` defined in <components.oas3.yaml#/components/headers/Retry-After>
 
 Modify [api.py:get_status](/edit/notebooks/oas3/api.py) such that:
 

connexion-101/050-reusing-and-bundling.md

@@ -41,13 +41,45 @@ See the [OAS website](https://github.com/OAI/OpenAPI-Specification).
 ### Exercise: replacing definitions with $refs
 
 - Open [ex-05-01-bundle.yaml](/edit/notebooks/oas3/ex-05-01-bundle.yaml)
-- replace as many definitions as possible with references from the shared [components.oas3.yaml]().
+- replace as many definitions as possible with references from the shared
+<https://raw.githubusercontent.com/ioggstream/python-course/refs/tags/v2026.05.1/connexion-101/notebooks/oas3/components.oas3.yaml>
+- "resolve" the OAS file as JSON, to ensure that anchors are removed.
 
 ```python
+import yaml, json
+d = yaml.safe_load(stream=open("oas3/ex-05-01-bundle-ok.yaml"))
+json.dump(d, open("oas3/bundle.json", "w+"))
+```
+
+----
+
+### Exercise: create a bundle from the previous file
+
+If you have docker, you can use the Redocly CLI to create a bundle from the previous file.
+
+A bundle is a single file containing all the resolved references. It can be used to share your API definition with others, or to deploy it to a server.
+
+```bash
 # Exercise: create a bundle from the previous file with
+docker run --rm -v $PWD:/app
+docker run --rm -v $PWD:/app docker.io/redocly/cli@sha256:78fa111b6c84522383d419a0631c984aefa76c5fbd39d8904a201b86e3b44168 bundle /app/oas3/bundle.json  --output /app/bundle.yaml
 ```
 
-### YAML anchors are your friends
+---
+
+## YAML as a template engine
+
+YAML can be used as a template engine for your OAS files. It allows you to define reusable components and reference them in your OAS file.
+
+```mermaid
+graph TD
+
+YAML[YAML OAS source]
+-->|processing| JSON[JSON OAS with $refs]
+-->|bundling| --> BUNDLE[OAS with resolved $refs]
+```
+
+----
 
 YAML has a nice feature, named **anchors**. They allow to define and reference
 given portions of a YAML file.
@@ -58,9 +90,10 @@ a: &this_is_an_anchor foo
 
 # *star dereferences the anchor
 b: *this_is_an_anchor
-
 ```
 
+----
+
 See [anchors.yaml](/edit/notebooks/anchors.yaml)
 
 ```python
@@ -73,6 +106,9 @@ content = Path('anchors.yaml').read_text()
 print(content)
 ```
 
+----
+
+Check anchor content:
 
 ```python
 ret = yaml.safe_load(content)
@@ -83,19 +119,48 @@ print(ret['foo'])
 print(ret['bar'])
 ```
 
-    {'name': 'Everyone has same name', 'age': 10}
-    {'name': 'Everyone has same name', 'age': 20}
+----
 
 ### Using YAML anchors in OAS3
 
+If you have a set of constants in your API definition
+e.g., maximum number of items in a list, or common responses, you can use YAML anchors to define them once and reuse them everywhere.
+
+```yaml
+openapi: 3.0.0
+...
+components:
+  schemas:
+    MaxItems:
+      type: integer
+      maximum: &max-items 100
+    Limit:
+      type: integer
+      maximum: *max-items  # Reuses the max-items anchor
+...
+```
+
+----
+
+### YAML merge keys
+
+Merge keys are a special feature of YAML that allows you to merge
+ the content of one or more dicts.
+ This can be useful when you have a set of common properties that you want to reuse across multiple objects.
+
+:warning: YAML merge keys are not supported by all YAML parsers, and they are not part of the OAS specification. While they are widely used on the web, they are formally deprecated in YAML 1.2.
+Nonetheles, I find them very useful to avoid using a specific template engine to generate OAS files and manage safely model composition without recurring to `allOf` and `oneOf` keywords, which might cause nesting and readability issues.
+
+
+
 As every operation may have a set of predefined responses, namely:
 
 - 503 Service Unavailable
 - 429 Too Many Requests
 
 You can put them in an `x-` custom parameter.which will be ignored by the OAS spec parser.
 
-```
+```yaml
 x-common-responses: &common-responses
   503ServiceUnavailable:
     $ref: ...
@@ -104,9 +169,11 @@ x-common-responses: &common-responses
 
 ```
 
+----
+
 Then use the `<<:` keyword and  `*anchor_name`  to reference them.
 
-```
+```yaml
 paths:
   /status:
     get:
@@ -120,10 +187,8 @@ paths:
           ...
 ```
 
-## NOTE: ANCHORS ARE PROCESSED BY THE YAML PARSER, NOT BY OAS
-
-## OAS knows nothing about ANCHORS
+:warning: ANCHORS ARE PROCESSED BY THE YAML PARSER, NOT BY OAS
+:warning: OAS knows nothing about ANCHORS
 
-```python
-
-```
+For YAML interoperability considerations
+see <https://www.rfc-editor.org/rfc/rfc9512.html>.

…101/060-connexion-authorization-basic.md …xion-101/060-security-confidentiality.mdconnexion-101/060-connexion-authorization-basic.md renamed to connexion-101/060-security-confidentiality.md connexion-101/060-connexion-authorization-basic.md renamed to connexion-101/060-security-confidentiality.md

@@ -92,7 +92,7 @@ def get_echo(tz, user=None):
 
 ### Test the my_auth implementation
 
-Run the spec in the [terminal](/terminals/1)
+Run the spec in the [terminal](/terminals/connexion)
 with the usual
 
 ```

…-101/070-connexion-throttling-headers.md …nnexion-101/070-security-availability.mdconnexion-101/070-connexion-throttling-headers.md renamed to connexion-101/070-security-availability.md connexion-101/070-connexion-throttling-headers.md renamed to connexion-101/070-security-availability.md

@@ -1,20 +1,19 @@
 # Throttling headers
 
-Service management is an essential component of a stable API Ecosystem.
+Service management is key for the reliability of an API ecosystem.
 
-Basic compontents for service management are communicating:
+Basic components for service management communicates:
 
 - when you are not operational, and explicit
   how long it will take to be up and running again;
 
 - if they are over quota and
   prevent overquota via throttling headers.
 
-
 While it could be annoying to explicitly state that every response
-should contain throttling headers, you can use yaml anchors for that!
+should contain throttling headers, you can use YAML anchors for that!
 
-```
+```yaml
 x-commons:
   throttling-headers: &throttling-headers
     X-RateLimit-Limit:
@@ -30,9 +29,9 @@ x-commons:
 
 Now we can use the anchor in our `get /echo responses`
 
-```
+```yaml
 paths:
-  /echo
+  /echo:
     get:
       ...
       operationId: api.get_echo
@@ -59,7 +58,7 @@ Use the `throttling_quota` utilities either:
 - or implement your own throttling
 
 
-```
+```python
 # Decorate with `throttle`
 from oas3.throttling_quota import throttle
 
@@ -70,7 +69,7 @@ def f(user='foo'):
 ```
 
 
-```
+```python
 # Or write your own using
 from oas3.throttling_quota import ThrottlingQuota
 
@@ -81,11 +80,6 @@ for i in range(4):
     print(ret)
 ```
 
-    {'limit': 3, 'remaining': 2, 'reset': 23, 'user': 'user1', 'comment': '2019-07-06T07:57:00'}
-    {'limit': 3, 'remaining': 1, 'reset': 23, 'user': 'user1', 'comment': '2019-07-06T07:57:00'}
-    {'limit': 3, 'remaining': 0, 'reset': 23, 'user': 'user1', 'comment': '2019-07-06T07:57:00'}
-    {'limit': 3, 'remaining': 0, 'reset': 23, 'user': 'user1', 'comment': '2019-07-06T07:57:00'}
-
 
 Modify [api.py:get_echo](/edit/notebooks/oas3/api.py) such that:
 
@@ -98,10 +92,9 @@ Modify [api.py:get_echo](/edit/notebooks/oas3/api.py) such that:
   - X-RateLimit-Remaining: remaining requests before the quota is consumed
 
 
-Now  [run the spec in a terminal](/terminals/1) using
+Now  [run the spec in a terminal](/terminals/connexion) using
 
-```
-cd /code/notebooks/oas3/
+```text
 connexion run /code/notebooks/oas3/ex-07-01-throttling-ok.yaml
 ```
 
@@ -111,11 +104,6 @@ and try making a request!
 
 
 
-```
+```python
 !curl http://localhost:5000/datetime/v1/echo -kv -ufoo:foo
 ```
-
-
-```
-
-```

connexion-101/073-security-integrity.md

@@ -0,0 +1,84 @@
+# Response integrity with Content-Digest
+
+```text
+SPEC_FILE=ex-07-02-integrity-ok.yaml uvicorn api_solution:main  --reload
+```
+
+Service management is not only about availability and quotas.
+
+Clients may also need a simple way to verify that the response body
+they received is exactly the one produced by the server.
+
+The HTTP fields `Want-Content-Digest` and `Content-Digest` can be used
+for that purpose:
+
+- the client sends `Want-Content-Digest` to ask for a digest in the response;
+
+- the server replies with `Content-Digest`, containing the digest of the
+  response body.
+
+In this lesson we only focus on describing these headers in the API
+contract. The implementation details of generating digests are out of scope.
+
+While it could be annoying to explicitly state these headers every time,
+you can define them once in shared components and reuse them from your
+operations.
+
+```yaml
+components:
+  parameters:
+    Want-Content-Digest:
+      $ref: 'components.oas3.yaml#/components/parameters/Want-Content-Digest'
+  headers:
+    Content-Digest:
+      $ref: 'components.oas3.yaml#/components/headers/Content-Digest'
+```
+
+## Requesting response digests
+
+Now we can use these reusable definitions in our `get /echo` operation.
+
+```yaml
+paths:
+  /echo:
+    get:
+      parameters:
+        - $ref: '#/components/parameters/tz'
+        - $ref: '#/components/parameters/Want-Content-Digest'
+      responses:
+        '200':
+          headers:
+            Content-Digest:
+              $ref: 'components.oas3.yaml#/components/headers/Content-Digest'
+          ...
+```
+
+### Exercise: document integrity headers
+
+Read the [ex-07-02-integrity-ok.yaml](/edit/notebooks/oas3/ex-07-02-integrity-ok.yaml)
+spec and identify:
+
+- where the `Want-Content-Digest` request header is declared;
+- where the `Content-Digest` response header is returned;
+- how the `get /echo` description explains this behavior to clients.
+
+### Exercise: run the API contract
+
+Run the spec in a terminal using:
+
+```text
+connexion run /code/notebooks/oas3/ex-07-02-integrity-ok.yaml
+```
+
+Then inspect the API from Swagger UI and try sending a request with
+the `Want-Content-Digest` header.
+
+For example:
+
+```python
+!curl http://localhost:5000/datetime/v1/echo -kv -ufoo:foo \
+  -H 'Want-Content-Digest: sha-256=1'
+```
+
+Check whether the response documents and exposes a `Content-Digest`
+header, and discuss how a client could use it to verify integrity.