openapi-content.tex

\section{OpenAPI Overview}

\begin{frame}{Why This Gets Its Own Short Overview}
\begin{itemize}
    \item Lab 3 is about building a REST-style API with Express.
    \item OpenAPI is how we write down the API contract clearly.
    \item The contract helps humans, tests, clients, and tools agree on what the server should do.
\end{itemize}

\vspace{0.35cm}

\begin{block}{Main idea}
The Express server is the thing that runs. The OpenAPI file is the written promise about how that server behaves.
\end{block}
\end{frame}

\begin{frame}{Where OpenAPI Fits}
\begin{center}
\begin{tikzpicture}[node distance=1.65cm]
    \node[clientserverbox] (client) {Client\\Application};
    \node[clientserverbox, right=of client] (api) {REST API\\Server};
    \node[clientserverbox, below=of api] (spec) {OpenAPI\\Document};

    \draw[archarrowboth] (client) -- node[archlabel] {HTTP + JSON} (api);
    \draw[archarrow] (spec) -- node[archlabel, right] {describes} (api);
    \draw[archarrow] (spec) -| node[archlabel, near start] {guides} (client);
\end{tikzpicture}
\end{center}

\vspace{0.25cm}

\begin{itemize}
    \item The client needs to know what requests are allowed.
    \item The server needs to return predictable responses.
    \item The spec records that agreement in YAML or JSON.
\end{itemize}
\end{frame}

\begin{frame}{The Problem OpenAPI Solves}
\begin{columns}[T,totalwidth=\textwidth]
    \begin{column}{0.48\textwidth}
        \begin{block}{Without a contract}
        \begin{itemize}
            \item Guess the URL
            \item Guess the JSON shape
            \item Guess the status codes
            \item Hope the README is current
        \end{itemize}
        \end{block}
    \end{column}
    \begin{column}{0.48\textwidth}
        \begin{block}{With OpenAPI}
        \begin{itemize}
            \item Routes are listed
            \item Schemas are defined
            \item Examples are visible
            \item Tools can validate it
        \end{itemize}
        \end{block}
    \end{column}
\end{columns}

\vspace{0.35cm}

\centering
\textbf{Old-fashioned engineering rule: write down the interface.}
\end{frame}

\section{The Basic Structure}

\begin{frame}{OpenAPI Is Not the API}
\begin{center}
\begin{tikzpicture}[node distance=1.55cm]
    \node[coursebox] (doc) {\textbf{OpenAPI Spec}\\YAML or JSON};
    \node[coursebox, below left=of doc] (human) {Human Docs\\Swagger UI / Redoc};
    \node[coursebox, below=of doc] (tests) {Validation\\Tests};
    \node[coursebox, below right=of doc] (clients) {Generated\\Clients};

    \draw[archarrow] (doc) -- (human);
    \draw[archarrow] (doc) -- (tests);
    \draw[archarrow] (doc) -- (clients);
\end{tikzpicture}
\end{center}

\vspace{0.2cm}

\begin{itemize}
    \item The spec describes expected behavior.
    \item Your Express routes still have to implement that behavior.
    \item The spec and code can drift if nobody checks them.
\end{itemize}
\end{frame}

\begin{frame}[fragile]{A Tiny OpenAPI File}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language={}]
openapi: 3.0.3
info:
  title: Items API
  version: 1.0.0
paths:
  /items:
    get:
      summary: List all items
      responses:
        "200":
          description: A list of items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
\end{lstlisting}

\vspace{0.15cm}

Even a small file can describe what route exists and what a successful response looks like.
\end{frame}

\begin{frame}{The Main Pieces}
\begin{center}
\begin{tikzpicture}[node distance=0.55cm]
    \node[monolithlayer] (openapi) {\textbf{openapi} -- spec version};
    \node[monolithlayer, below=of openapi] (info) {\textbf{info} -- title, version, description};
    \node[monolithlayer, below=of info] (servers) {\textbf{servers} -- base URLs};
    \node[monolithlayer, below=of servers] (paths) {\textbf{paths} -- routes and HTTP methods};
    \node[monolithlayer, below=of paths] (components) {\textbf{components} -- reusable schemas, parameters, responses};
\end{tikzpicture}
\end{center}
\end{frame}

\begin{frame}{Lab 3 API at a Glance}
\begin{center}
\begin{tabular}{lll}
\textbf{Method} & \textbf{Path} & \textbf{Purpose} \\
GET & \texttt{/health} & Check that the server is running \\
GET & \texttt{/items} & Get all items \\
POST & \texttt{/items} & Create a new item \\
GET & \texttt{/items/\{id\}} & Get one item \\
PUT & \texttt{/items/\{id\}} & Update one item \\
DELETE & \texttt{/items/\{id\}} & Delete one item \\
\end{tabular}
\end{center}

\vspace{0.35cm}

\begin{block}{Teaching point}
This table is what most students expect a README to say. OpenAPI says the same thing in a tool-readable form.
\end{block}
\end{frame}

\section{Paths, Methods, and Responses}

\begin{frame}{Paths Describe Resources}
\begin{itemize}
    \item A path is the URL pattern after the server base URL.
    \item Each path can have one or more HTTP methods.
    \item The method describes the kind of action being requested.
\end{itemize}

\vspace{0.3cm}

\begin{center}
\begin{tabular}{ll}
\textbf{HTTP Method} & \textbf{Typical REST Meaning} \\
GET & Read a resource \\
POST & Create a resource \\
PUT & Replace a resource \\
PATCH & Partially update a resource \\
DELETE & Delete a resource \\
\end{tabular}
\end{center}
\end{frame}

\begin{frame}[fragile]{Path Parameters}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language={}]
paths:
  /items/{id}:
    get:
      summary: Get one item by ID
      parameters:
        - $ref: "#/components/parameters/ItemId"
      responses:
        "200":
          description: The requested item
        "404":
          description: Item not found
\end{lstlisting}

\vspace{0.15cm}

\textbf{Rule of thumb:} every \texttt{\{thing\}} in the path needs a matching parameter definition.
\end{frame}

\begin{frame}[fragile]{Reusable Parameters}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language={}]
components:
  parameters:
    ItemId:
      name: id
      in: path
      required: true
      description: Numeric item ID
      schema:
        type: integer
        example: 1
\end{lstlisting}

\vspace{0.15cm}

Using \texttt{components} avoids repeating the same parameter definition for GET, PUT, and DELETE.
\end{frame}

\begin{frame}{Status Codes Are Part of the Contract}
\begin{center}
\begin{tabular}{ll}
\textbf{Code} & \textbf{Meaning in this lab} \\
200 & Request succeeded \\
201 & Item was created \\
204 & Item was deleted; no body returned \\
400 & Request body is invalid \\
404 & Requested item was not found \\
500 & Server failed unexpectedly \\
\end{tabular}
\end{center}

\vspace{0.35cm}

\begin{itemize}
    \item Document the normal case and the common failure cases.
    \item A useful client must know what can work and what can fail.
\end{itemize}
\end{frame}

\section{Schemas and Request Bodies}

\begin{frame}[fragile]{Schemas Describe JSON Shape}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language={}]
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: keyboard
        quantity:
          type: number
          example: 10
      required: [id, name, quantity]
\end{lstlisting}

\vspace{0.15cm}

Schemas answer: \textbf{What fields exist? What types are allowed? What is required?}
\end{frame}

\begin{frame}[fragile]{Input and Output Are Different}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language={}]
Item:
  required: [id, name, quantity]

ItemInput:
  required: [name, quantity]
\end{lstlisting}

\vspace{0.2cm}

\begin{itemize}
    \item The client sends \texttt{name} and \texttt{quantity}.
    \item The server creates the \texttt{id}.
    \item That means request and response schemas do not always match.
\end{itemize}
\end{frame}

\begin{frame}[fragile]{Request Bodies}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language={}]
paths:
  /items:
    post:
      summary: Create a new item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemInput"
      responses:
        "201":
          description: Item created
\end{lstlisting}

\vspace{0.2cm}

The schema should match what Express expects to read from \texttt{req.body}.
\end{frame}

\begin{frame}[fragile]{Error Responses Need Schemas Too}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language={}]
ErrorResponse:
  type: object
  properties:
    error:
      type: string
      example: Item not found
  required:
    - error
\end{lstlisting}

\vspace{0.2cm}

\begin{block}{Why this matters}
Clients should not have to guess whether an error is returned as \texttt{error}, \texttt{message}, \texttt{msg}, or a plain string.
\end{block}
\end{frame}

\section{Using OpenAPI in Practice}

\begin{frame}{Spec First or Code First?}
\begin{columns}[T,totalwidth=\textwidth]
    \begin{column}{0.48\textwidth}
        \begin{block}{Spec first}
        \begin{itemize}
            \item Design the contract first
            \item Then implement routes
            \item Good for teams and grading
        \end{itemize}
        \end{block}
    \end{column}
    \begin{column}{0.48\textwidth}
        \begin{block}{Code first}
        \begin{itemize}
            \item Write routes first
            \item Generate or write docs after
            \item Easy to start; drift is danger
        \end{itemize}
        \end{block}
    \end{column}
\end{columns}

\vspace{0.35cm}

\centering
\textbf{For this course: learn the contract, then make the code match it.}
\end{frame}

\begin{frame}{What Tools Can Do With It}
\begin{itemize}
    \item Render interactive documentation.
    \item Mock an API before the server is finished.
    \item Validate requests and responses.
    \item Generate client code or server stubs.
    \item Support tests that compare real behavior to the contract.
\end{itemize}

\vspace{0.35cm}

\begin{center}
\begin{tikzpicture}[node distance=1.35cm]
    \node[clientserverbox] (yaml) {openapi.yaml};
    \node[clientserverbox, right=of yaml] (docs) {Docs};
    \node[clientserverbox, below=of docs] (mock) {Mocks};
    \node[clientserverbox, left=of mock] (tests) {Tests};

    \draw[archarrow] (yaml) -- (docs);
    \draw[archarrow] (yaml) |- (mock);
    \draw[archarrow] (yaml) -- (tests);
\end{tikzpicture}
\end{center}
\end{frame}

\begin{frame}[fragile]{Serving Docs From Express}
\begin{lstlisting}[style=code,basicstyle=\ttfamily\scriptsize,language=JavaScript]
import express from 'express';
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const app = express();
const openapi = YAML.load('./openapi.yaml');

app.use('/docs', swaggerUi.serve, swaggerUi.setup(openapi));
\end{lstlisting}

\vspace{0.15cm}

This does not magically implement the API. It only displays the contract. No fairy dust, no tiny REST goblins.
\end{frame}

\begin{frame}{Common Student Mistakes}
\begin{itemize}
    \item Documenting a route that does not exist in Express.
    \item Implementing a route that is missing from OpenAPI.
    \item Returning a different JSON shape than the schema says.
    \item Forgetting failure responses such as 400 and 404.
    \item Treating examples as validation rules.
\end{itemize}

\vspace{0.35cm}

\begin{block}{Good habit}
After changing routes, update the spec or the tests immediately. Do not leave the contract stale.
\end{block}
\end{frame}

\section{How This Connects to Lab 3}

\begin{frame}{Lab 3 Mental Model}
\begin{center}
\begin{tikzpicture}[node distance=1.3cm]
    \node[clientserverbox] (readme) {README\\Human instructions};
    \node[clientserverbox, right=of readme] (openapi) {OpenAPI\\Machine-readable contract};
    \node[clientserverbox, below=of openapi] (express) {Express\\Implementation};
    \node[clientserverbox, left=of express] (tests) {Tests\\Evidence};

    \draw[archarrowboth] (readme) -- (openapi);
    \draw[archarrow] (openapi) -- node[archlabel, right] {should match} (express);
    \draw[archarrow] (tests) -- node[archlabel] {check} (express);
    \draw[archarrow] (tests) -- node[archlabel, left] {can compare} (openapi);
\end{tikzpicture}
\end{center}

\vspace{0.2cm}

\centering
The goal is not pretty YAML. The goal is a clear, testable API contract.
\end{frame}

\begin{frame}{What Students Should Be Able To Do}
\begin{itemize}
    \item Read an OpenAPI file and identify the available routes.
    \item Explain the request and response shape for each route.
    \item Match Express route behavior to the documented contract.
    \item Add or update a small path, schema, or response.
    \item Notice when code and documentation disagree.
\end{itemize}
\end{frame}

\begin{frame}{Takeaways}
\begin{itemize}
    \item OpenAPI is a contract for HTTP APIs.
    \item It documents paths, methods, parameters, bodies, schemas, and responses.
    \item Tools can turn the contract into docs, mocks, validation, and generated code.
    \item The hard part is keeping the contract honest.
\end{itemize}

\vspace{0.45cm}

\centering
\Large \textbf{A client/server system is easier to build when the interface is written down.}
\end{frame}