API Design and Integration: Four-Week Online Course

A four-week online course on designing and consuming REST APIs, taught on Smarter’s API from both sides. Smarter’s API has sixteen commands under /api/v1/cli/ that apply, describe and delete every resource from a YAML manifest, resource-style endpoints for the web console, API keys of which only a hash is stored, one error format for every failure, and Swagger and ReDoc pages generated from the code. Its clients are real and public: the Go smarter-cli, the React web console, the @smarter.sh/ui-chat npm package, whose types are generated from the chat API’s Pydantic contract, and a Python SDK that has drifted from the API it calls. There are twelve 30-minute recorded lectures and a 90-minute live session each week. Week 1 covers consuming an API, week 2 building clients, week 3 the server side, and week 4 evolving, securing and operating an API. See Course Formats and Grading for the format, the grading scale and the course policies, and API Design and Integration for an overview of the subject.

At a Glance

Students

Developers who build or integrate with web APIs.

Deployment

A shared Smarter instance with an API key for each student in weeks 1 and 2. Students install Smarter from source for week 3.

Workload

3 hours of instruction and 4 to 6 hours of assignments each week.

Cost

Free, apart from small model charges.

Learning Objectives

By the end of the course, students can:

  1. Apply REST principles, and explain where real APIs depart from them.

  2. Call authenticated APIs, handle errors, and write robust client libraries.

  3. Read and write OpenAPI descriptions, and generate clients and documentation from them.

  4. Implement an endpoint in Django REST Framework with authentication, validation and consistent errors.

  5. Evaluate an API against a style guide and the OWASP API Security Top 10.

  6. Design API changes with versioning, deprecation and migration plans.

Technical Prerequisites

  • Required: structured programming in at least one language, including HTTP requests and JSON parsing.

  • Required: HTTP, JSON and YAML.

  • Required: the command line, curl, Git and a GitHub account.

  • Required by week 3: basic Python, Docker basics, and Smarter installed from source (see the Developer Setup Guide).

  • Helpful: Postman, and basic Django.

Schedule

The files that the lectures refer to are listed in full under Smarter in the Source Code.

Week

Item

Content

1

Lecture 1

What makes an API good. REST principles, resources, methods, idempotence and status codes.

1

Lecture 2

Smarter’s API. The REST API, its commands, Swagger documentation, and the manifest-based design.

1

Lecture 3

Authentication and errors. API keys and sessions, authentication, the error format, and RFC 9457.

1

Live session 1

Live curl session through a resource’s lifecycle, and an error hunt in pairs. Start Assignment 1.

2

Lecture 4

Client design. Configuration, authentication, typed responses, and idiomatic interfaces.

2

Lecture 5

Resilient clients. Timeouts, retries, backoff, idempotency keys, and rate limits.

2

Lecture 6

Chat and streaming APIs. Smarter’s chat API, streaming, and OpenAI-compatible Proxies.

2

Live session 2

Review of Assignment 1. Code review of clients in small groups. Start Assignment 2.

3

Lecture 7

Inside the server. How Smarter’s API is built with Django REST Framework: URLs, views, authentication classes and brokers, and the three styles side by side: command-style /api/v1/cli/, resource-style /api/v1/guardrails/, and the console’s react-integration/api/.

3

Lecture 8

Contracts. Pydantic request and response models, OpenAPI generation, and contract tests.

3

Lecture 9

Describing an API. Writing OpenAPI by hand, generating clients, and documentation that developers enjoy.

3

Live session 3

Review of Assignment 2. Live addition of an endpoint, with tests. Capstone proposals discussed. Start Assignment 3.

4

Lecture 10

Evolving an API. Versioning strategies, deprecation, breaking changes, and ADR 023.

4

Lecture 11

Securing an API. The OWASP API Security Top 10: object-level authorization, excessive data exposure, mass assignment and rate limiting.

4

Lecture 12

Operating an API. Rate limiting: DRF’s throttling classes (Rate Limiting), which Smarter does not configure, against what it uses instead: Budgets that limit spending and tokens, and middleware that blocks probing clients. Is that enough? Logging, monitoring and service level objectives.

4

Live session 4

Capstone presentations (about 6 minutes each, with 2 minutes of questions), and a course retrospective.

Assignments 1 to 3 are due before the next live session. Assignment 4 is due in the middle of week 4. The capstone proposal is due before Live session 3, and the capstone at the start of Live session 4.

Smarter in the Source Code

Every lecture, lab and assignment in this course rests on the files below, on both sides of one API: the server in github.com/smarter-sh/smarter, and the clients in their own repositories. Every reference is to the main branch, so that students can open each one during class. Python paths are under smarter/smarter/.

The Server

Topic

What Smarter does

Where to look

One API for every resource

Sixteen commands under /api/v1/cli/: apply, validate, get, describe, delete, deploy, undeploy, logs, example-manifest, json-schema, prompt, status, version, whoami and the rest. Each resource-specific command takes the kind in the path, and the request body is a YAML manifest. ADR 006.

api/v1/cli/urls.py, api/v1/cli/views/

Three styles side by side

Beside the command-style CLI API, each resource family has resource-style DRF endpoints, such as /api/v1/guardrails/<id>/events/, and the web console’s list pages call a third set, authenticated by the session, under react-integration/api/, to list, clone, rename and delete. Comparing them is a lesson in API style.

api/v1/urls.py, guardrail/api/v1/urls.py, guardrail/urls.py

From URL to database

Each view finds the broker for the kind, and the broker turns the manifest into Django models and back. ADR 024.

api/v1/cli/brokers.py, lib/manifest/

Versioning

The version is in the path (/api/v1/) and in every manifest (apiVersion: smarter.sh/v1). When the schema command was renamed json-schema, the old path was kept as a permanent redirect, because the VS Code extension still calls it. ADR 023.

api/v1/urls.py, api/v1/manifests/version.py, api/v1/cli/urls.py

Authentication

API keys built on Django REST Knox. Only a hash of each key is stored, compared in constant time, and every key can be deactivated. Every endpoint requires authentication by default.

lib/drf/token_authentication.py, lib/drf/models.py, settings/base.py (REST_FRAMEWORK)

Errors

One base view maps every exception to a status code, and returns it in one JSON format, which is also written to the journal. Authentication failures are returned as 403, not 401: a choice worth reviewing against a style guide.

api/v1/cli/views/base.py, lib/journal/http.py

Self-description

Every kind publishes a JSON Schema and an example manifest through the API, and the whole API is described with OpenAPI, in Swagger and ReDoc pages generated by drf-yasg.

api/v1/cli/views/schema.py, api/v1/cli/views/swagger.py, docs/urls.py

A contract as code

The chat API’s requests and responses are Pydantic models. Their JSON Schema is exported, committed, and tested to be current, and the React chat’s TypeScript types are generated from it. The Chat API Contract.

prompt/contract/models.py, chat-contract.schema.json

Compatibility as strategy

A Proxy passes requests through to a provider’s own API, unchanged, so callers keep the OpenAI, Anthropic or Gemini SDK and change only the base URL and the key. Smarter Proxy.

apps/proxy/, proxy/data/proxy/

Limits on abuse

Smarter does not configure DRF throttling. Spending and token use are limited by Budgets, and middleware blocks clients that probe for missing pages or sensitive files. Students can judge whether that is enough.

lib/django/middleware/excessive_404.py, user-hourly-token-throttle.yaml

The Clients

Client

What it shows

Where to look

The smarter CLI

A Go command-line client with one subcommand per API command, distributed for macOS, Linux and Windows. Its configuration, API key and host override are in one file.

smarter-cli, cmd/api.go, cmd/apply.go

The web console and chat

React apps that call the same API with the user’s session, and a chat component published to npm as @smarter.sh/ui-chat.

smarter/react/packages/, smarter-chat

The Python SDK

A small Python client, last updated in July 2025, which still calls LLMClients by their former name, chatbots: a real example of a client that has drifted from its API.

smarter-python, smarter/api/client.py

Validation in the editor

A VS Code extension that validates manifests against JSON Schemas. VS Code Extension.

smarter-vscode-yaml

Graded Assignments

Assignment 1: Lifecycle and Error Catalog

Students take a resource through its lifecycle with curl and the CLI, and catalog at least six distinct errors, judging each against what a client needs.

Turn in: a Markdown file with commands, responses and an error table.

Criterion

Pts

Exemplary

Developing

Lifecycle

5

All steps with curl and the CLI; no key committed.

Steps missing.

Error variety

5

Six or more classes.

Variations of one.

Assessment

6

Judged against recovery needs.

None.

Improvement

4

Better responses proposed.

None.

Assignment 2: A Resilient Client

Students write a client that lists LLMClients, applies a manifest and chats, with timeouts, retries with backoff for transient errors only, and typed responses, tested with mocked responses.

Turn in: a Git repository with the client, tests and a README.md.

Criterion

Pts

Exemplary

Developing

Works

5

All three operations.

Some.

Resilience

6

Timeouts; retries only for transient, safe failures.

No timeouts, or retries everything.

Tests

5

Mocked, including failures.

Needs a live server.

Interface and docs

4

Idiomatic and documented.

Raw HTTP exposed.

Assignment 3: A New Endpoint

Students add a small read-only endpoint to their fork of Smarter, for example one that returns the caller’s API keys with their creation and last-used dates (never the key itself), with a Pydantic response model, authentication, tests and Swagger documentation.

Turn in: a pull request against their fork.

Criterion

Pts

Exemplary

Developing

Security

6

Authenticated, scoped to the caller, no secrets exposed, tested.

Exposes other users’ data or secrets.

Consistency

5

Matches the existing API’s conventions and errors.

Inconsistent.

Tests

5

Success, unauthenticated and other-user cases.

Happy path only.

Documentation

4

Appears correctly in Swagger.

Missing.

Assignment 4: Security Review

Students review part of Smarter’s API against the OWASP API Security Top 10, with evidence from real requests, and report findings by severity. Any real weakness is reported privately to the maintainers, as described in the project’s security policy, not in the assignment.

Turn in: a two-page review.

Criterion

Pts

Exemplary

Developing

Coverage

5

Every relevant category examined.

A few categories.

Evidence

6

Real requests and responses.

Assertions.

Analysis

5

Explains which defenses exist, and where.

Lists categories without analysis.

Responsible handling

4

Real weaknesses reported privately.

Weakness details published.

Capstone Projects

Students choose one, propose it before Live session 3, and present it in Live session 4.

Capstone A: A Published SDK

Learning objective. Design, test, document and publish a client SDK as an open source package.

Students write an SDK for the Smarter API in a language that lacks one, with typed responses, mapped errors, resilient transport, tests, documentation and continuous integration, and publish a pre-release version to the language’s package registry (for example a 0.1.0 on npm, PyPI, crates.io or pkg.go.dev).

What students turn in:

  • A public Git repository with the SDK, tests, CI and documentation.

  • A link to the published package.

  • A six-minute presentation with a live demonstration.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Interface

20

Idiomatic and consistent.

Thin HTTP wrapper.

Robustness

20

Typed, mapped errors, safe retries, timeouts.

Fragile.

Tests and CI

20

Mocked tests run in CI on every push.

No CI, or live-server tests.

Documentation

20

Quick start and reference for every operation.

Sparse.

Publishing and presentation

20

Published with a license and changelog; clear demonstration.

Not published.

Capstone B: An API Improvement, from ADR to Release

Learning objective. Take an API change from design to implementation, with compatibility proven by tests and a deprecation plan.

Students choose a weakness found in their reviews, write an ADR with an OpenAPI fragment and migration plan, implement the change on their fork of Smarter, add deprecation warnings for the old behavior, and write tests that run old and new clients against it.

What students turn in:

  • An ADR in the format of ADR.

  • A pull request against their fork with the implementation, tests and documentation.

  • A migration guide for client developers.

  • A six-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

ADR

20

Real problem, alternatives compared, consequences stated.

Thin.

Implementation

20

Correct and consistent with the API.

Inconsistent.

Compatibility

25

Tests prove old clients work; deprecation signaled.

Untested.

Migration guide

20

A client developer could follow it.

Vague.

Presentation

15

Clear and on time.

Overruns.

Further Study