API Design and Integration: Classroom Bootcamp

An eight-hour classroom bootcamp on designing and consuming REST APIs, taught on Smarter’s versioned and documented API, from both sides: the server that provides it and the clients built on it. 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. Students call the API by hand, write a client, review the API against a style guide, and design an improvement that does not break existing clients. See Course Formats and Grading for the standard bootcamp day, the grading scale and the course policies, and API Design and Integration for an overview of the subject.

At a Glance

Students

Developers in any language who build or integrate with web APIs.

Deployment

A shared Smarter instance run by the instructor, with an API key for each student, or students’ own installations from the Quick Start.

Cost

Free, apart from small model charges for chat requests.

Learning Objectives

By the end of the bootcamp, students can:

  1. Explain the principles of REST: resources, methods, status codes, representations and statelessness.

  2. Call an authenticated API with curl and a client library, and handle its errors.

  3. Read and use OpenAPI (Swagger) documentation.

  4. Evaluate an API against a published style guide.

  5. Design a change to an API, with a versioning and migration plan that does not break clients.

Technical Prerequisites

  • Required: structured programming in at least one language (Python, JavaScript, Go, Java or similar), including making HTTP requests and parsing JSON.

  • Required: HTTP: methods, status codes, headers and bodies.

  • Required: JSON and YAML.

  • Required: the command line and curl.

  • Required: Git and a GitHub account.

  • Helpful: Postman or a similar API client, and the smarter CLI.

Schedule

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

Block

Min

Content

1

45

Lecture 1: What makes an API good. REST principles, resources and representations, methods and idempotence, status codes, and consistency. A first look at Smarter’s REST API and its Swagger documentation.

2

45

Lab 1: Call it by hand. With curl and an API key, apply, get, describe and delete a resource through /api/v1/cli/, then do the same with the smarter CLI, and compare. Produces Assignment 1.

3

45

Lecture 2: Authentication and errors. API keys, tokens and sessions; Smarter’s authentication and its error format. Problem details (RFC 9457), and what a client needs from an error.

4

45

Lab 2: Make it fail. Trigger at least five different errors (bad key, missing resource, invalid manifest, wrong method, a budget limit) and record each status code and body. Produces Assignment 2.

5

45

Lecture 3: Writing a client. Wrapping an API in a small library: configuration, authentication, retries, timeouts, pagination and typed responses. A tour of how the Go smarter-cli calls the API (cmd/api.go), and of the Python SDK, which still calls LLMClients chatbots.

6

45

Lecture 4: Chat APIs and streaming. Smarter’s chat API, conversation state, and streaming responses. The OpenAI-compatible Proxy, and why compatibility with a popular API is a design strategy.

7

45

Lab 3: Write a client. In a language of their choice, students write a small client that lists their LLMClients and sends a chat message to one. Produces Assignment 3.

8

45

Lecture 5: Evolving an API. Versioning strategies (path, header, media type), deprecation, breaking and non-breaking changes, and Smarter’s ADR 023 on API versioning.

9

45

Lab 4: Style guide review. In groups, review part of Smarter’s API against Google’s or Zalando’s guidelines, and list where it follows them and where it does not. Ungraded.

10

45

Lecture 6: 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, the journal of every request, monitoring, documentation, and the OWASP API Security Top 10.

11

30

Capstone kickoff. Students choose a capstone and outline their design or client.

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: Resource Lifecycle by Hand

Students take one resource through its whole lifecycle with curl, then with the CLI, and compare the two.

Turn in: a Markdown file with every command and response, and a half-page comparison.

Criterion

Pts

Exemplary

Developing

Complete lifecycle

6

Apply, get, describe and delete, all successful.

Some steps missing or failing.

Correct requests

5

Correct methods, headers and bodies; no API key committed.

Errors in requests, or a real key in the file.

Responses explained

5

Status codes and bodies interpreted.

Pasted without comment.

Comparison

4

Explains what the CLI does for the user.

Superficial.

Assignment 2: Error Catalog

Students trigger at least five different errors and catalog them, then judge whether each error gives a client what it needs to recover.

Turn in: a table of request, status code, body and assessment.

Criterion

Pts

Exemplary

Developing

Variety

5

Five or more distinct error classes.

Variations of one error.

Accuracy

5

Real requests and responses.

Paraphrased.

Assessment

6

Judges each error against what a client needs (code, message, field, retry).

No assessment.

Improvement

4

Proposes a better response for the weakest error.

None.

Assignment 3: A Small Client

Students write a client in the language of their choice that lists their LLMClients and chats with one, reading the API key from an environment variable.

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

Criterion

Pts

Exemplary

Developing

Works

6

Lists LLMClients and completes a chat.

One of the two works.

Error handling

5

Handles bad keys, timeouts and server errors with clear messages.

Crashes on errors.

Secrets

4

Key from the environment, never in the repository.

Key in the code.

Documentation

5

Someone else could run it.

Missing setup steps.

Capstone Projects

Students choose one. Capstones are due one week after the bootcamp.

Capstone A: A Client Library

Learning objective. Design a client library that makes an API easy and safe to use, with typed responses, errors and tests.

Students write a small client library for part of the Smarter API in a language of their choice, covering authentication, apply, get, describe, delete and chat, with typed response objects, exceptions that map to the API’s errors, retries for transient failures, and tests that use recorded or mocked responses.

What students turn in:

  • A Git repository with the library, tests and a README.md with examples.

  • A short example program that uses it.

  • A one-page design note on the library’s interface.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Interface design

25

Idiomatic for the language, consistent, hard to misuse.

A thin wrapper around raw HTTP calls.

Errors and retries

20

Errors mapped to exceptions; retries only for safe, transient failures.

Generic exceptions; retries for everything.

Typed responses

15

Responses parsed into typed objects.

Raw dictionaries.

Tests

20

Mocked or recorded responses, including errors.

Tests that need a live server, or none.

Documentation

20

Examples for every operation.

Sparse.

Capstone B: An API Change Proposal

Learning objective. Design an improvement to a real API, and plan its release so that no existing client breaks.

Students identify one weakness in Smarter’s API (from their style guide review, for example inconsistent naming, missing pagination or an unhelpful error) and write a design proposal as an Architecture Decision Record, with the new OpenAPI description and a migration plan.

What students turn in:

  • An ADR in the format of ADR, with context, decision, alternatives and consequences.

  • The OpenAPI fragment for the new or changed endpoint.

  • A migration plan: how old and new clients coexist, how deprecation is announced, and when the old behavior is removed.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Problem

20

A real weakness, with evidence and the style guide rule it breaks.

A matter of taste.

Design

25

Consistent with the rest of the API and with the style guide.

Fixes one thing, breaks consistency elsewhere.

Alternatives

15

At least two alternatives, fairly compared.

None.

Compatibility and migration

25

No existing client breaks; clear deprecation timeline.

Breaks clients, or no plan.

Writing

15

Clear and concise, in ADR form.

Long or disorganized.

Further Study