responder/examples.html

<!DOCTYPE html>

<html lang="en" data-content_root="./">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Examples &#8212; responder 9.2.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=5ecbeea2" />
    <link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
    <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=eb4102c5" />
    <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
    <link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" />
    <link rel="stylesheet" type="text/css" href="_static/design-elements.e5416f61bae5d36adc6d722a2b6f8cff.css?v=452a8e97" />
    <script src="_static/documentation_options.js?v=e8b940be"></script>
    <script src="_static/doctools.js?v=fd6eb6e6"></script>
    <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/clipboard.min.js?v=a7894cd8"></script>
    <script src="_static/copybutton.js?v=fd10adb8"></script>
    <script>
    </script>
    <script src="_static/design-tabs.js?v=f930bc37"></script>
    <script src="_static/design-elements.bbdccc18c4abea9397628f9fea3d48c2.js?v=03c7770e"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Composing Apps with Routers" href="routers.html" />
    <link rel="prev" title="Feature Tour" href="tour.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  

  
  

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <section id="examples">
<h1>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h1>
<p>The <code class="docutils literal notranslate"><span class="pre">examples/</span></code> directory is the quickest way to see Responder’s pieces
working together. Each file is a small app you can run directly, poke with
<code class="docutils literal notranslate"><span class="pre">curl</span></code>, and copy from when you need the same pattern in your own service.</p>
<section id="running-an-example">
<h2>Running an Example<a class="headerlink" href="#running-an-example" title="Link to this heading">¶</a></h2>
<p>From an installed environment, run an example with the Responder CLI:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ responder run examples/helloworld.py
</pre></div>
</div>
<p>Then call it from another terminal:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ curl http://127.0.0.1:5042/hello
hello, world!
</pre></div>
</div>
<p>When you are working from a checkout of this repository, prefix the command
with <code class="docutils literal notranslate"><span class="pre">uv</span> <span class="pre">run</span></code> so the project environment is used:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ uv run responder run examples/rest_api.py
</pre></div>
</div>
<p>Most examples expose interactive OpenAPI docs at <code class="docutils literal notranslate"><span class="pre">/docs</span></code>. Open
<code class="docutils literal notranslate"><span class="pre">http://127.0.0.1:5042/docs</span></code> in a browser after starting one of the API
examples.</p>
</section>
<section id="where-to-start">
<h2>Where to Start<a class="headerlink" href="#where-to-start" title="Link to this heading">¶</a></h2>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">helloworld.py</span></code></dt><dd><p>The smallest useful app: one index route, one route parameter, and no
sessions. Start here if you want to see the request/response shape.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">rest_api.py</span></code></dt><dd><p>A compact book catalog with Pydantic input models, response models,
OpenAPI metadata, <code class="docutils literal notranslate"><span class="pre">resp.created()</span></code>, <code class="docutils literal notranslate"><span class="pre">resp.no_content()</span></code>, and
<code class="docutils literal notranslate"><span class="pre">resp.problem()</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">todo.py</span></code></dt><dd><p>The practical all-around example: typed input, filtering, bearer-token
auth, named auth policies, request IDs, and richer OpenAPI examples.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">atelier.py</span></code></dt><dd><p>The contract-test fixture. It is intentionally polished because the test
suite validates its generated OpenAPI document and drives a generated
client against it.</p>
</dd>
</dl>
</section>
<section id="focused-patterns">
<h2>Focused Patterns<a class="headerlink" href="#focused-patterns" title="Link to this heading">¶</a></h2>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">user.py</span></code></dt><dd><p>A smaller typed CRUD-style API for users.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">shortlinks.py</span></code></dt><dd><p>Redirects, conflict responses, generated short codes, and click tracking.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">webhooks.py</span></code></dt><dd><p>Raw-body signature verification before JSON validation, useful for
Stripe-style webhook receivers.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fortunes.py</span></code></dt><dd><p>A local-command wrapper that turns the <code class="docutils literal notranslate"><span class="pre">fortune</span></code> CLI into an API and
reports command failures as problem-details responses. Install the
<code class="docutils literal notranslate"><span class="pre">fortune</span></code> command, or set <code class="docutils literal notranslate"><span class="pre">FORTUNE_COMMAND</span></code> to a compatible command.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">lifespan.py</span></code></dt><dd><p>Startup and shutdown work with an async lifespan context manager.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">sse_stream.py</span></code></dt><dd><p>Server-Sent Events with heartbeat support and a tiny browser page.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">websocket_chat.py</span></code></dt><dd><p>A minimal WebSocket chat room with a shared in-memory hub.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">marimo_mount.py</span></code></dt><dd><p>Mounts a marimo notebook under <code class="docutils literal notranslate"><span class="pre">/notebooks/</span></code> while keeping normal
Responder routes and OpenAPI docs on the parent app. Install marimo first:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ uv pip install marimo
</pre></div>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">tarot.py</span></code></dt><dd><p>A larger read/browse/deal API with Pydantic models and repeatable example
data.</p>
</dd>
</dl>
</section>
<section id="testing-examples">
<h2>Testing Examples<a class="headerlink" href="#testing-examples" title="Link to this heading">¶</a></h2>
<p>Several examples expose a <code class="docutils literal notranslate"><span class="pre">create_api()</span></code> function so tests can build a fresh
app with a fake store or fake external dependency. For example,
<code class="docutils literal notranslate"><span class="pre">examples/fortunes.py</span></code> accepts a <code class="docutils literal notranslate"><span class="pre">fortune_reader</span></code> callable, which lets the
test suite verify the API contract without depending on the local
<code class="docutils literal notranslate"><span class="pre">fortune</span></code> binary.</p>
<p>That shape is a good habit for your own apps too: keep route wiring in
<code class="docutils literal notranslate"><span class="pre">create_api()</span></code>, pass real dependencies in production, and pass fakes in
tests.</p>
</section>
</section>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><p class="logo">
  <a href="index.html">
    <img class="logo" src="_static/responder.png" />
  </a>
</p>
<p>
  <strong>Responder</strong> — a familiar HTTP service framework for Python.
  <br />
  <small>v9.2.0</small>
</p>
<h3>Useful Links</h3>
<ul>
  <li><a href="https://github.com/kennethreitz/responder">Responder @ GitHub</a></li>
  <li><a href="https://pypi.org/project/responder/">Responder @ PyPI</a></li>
  <li><a href="https://github.com/kennethreitz/responder/issues">Issue Tracker</a></li>
</ul><h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start</a></li>
<li class="toctree-l1"><a class="reference internal" href="tour.html">Feature Tour</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Examples</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#running-an-example">Running an Example</a></li>
<li class="toctree-l2"><a class="reference internal" href="#where-to-start">Where to Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="#focused-patterns">Focused Patterns</a></li>
<li class="toctree-l2"><a class="reference internal" href="#testing-examples">Testing Examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="routers.html">Composing Apps with Routers</a></li>
<li class="toctree-l1"><a class="reference internal" href="guide-config.html">Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="clientgen.html">Generated Clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="deployment.html">Deployment</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial-rest.html">Building a REST API</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-sqlalchemy.html">Using SQLAlchemy</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-auth.html">Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-websockets.html">WebSocket Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-middleware.html">Writing Middleware</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-flask.html">Migrating from Flask</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command Line Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="runtime-contracts.html">Runtime Contracts</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Project</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changes.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v9.html">Migrating to v9</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v8.html">Migrating to v8</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v7.html">Migrating to v7</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v6.html">Migrating to v6</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration-v5.html">Migrating to v5</a></li>
<li class="toctree-l1"><a class="reference internal" href="sandbox.html">Sandbox</a></li>
<li class="toctree-l1"><a class="reference internal" href="backlog.html">Backlog</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
      <li>Previous: <a href="tour.html" title="previous chapter">Feature Tour</a></li>
      <li>Next: <a href="routers.html" title="next chapter">Composing Apps with Routers</a></li>
  </ul></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &#169;2018-2026, Kenneth Reitz.
      
      |
      <a href="_sources/examples.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    
    <a href="https://github.com/kennethreitz/responder" class="github">
        <img src="_static/forkme_right_darkblue.png" alt="Fork me on GitHub" class="github"/>
    </a>
    

    
  </body>
</html>