Building a Recipe API with Cooklang | Cooklang: recipe markup language

Most recipe APIs charge per request, lock your data into their schema, and limit what you can do with recipes you own. There's a simpler path: your .cook files already contain structured data. CookCLI can expose that data as JSON, run a local server, and give you everything you need to build a recipe app — without signing up for anything.

This post walks through using CookCLI as a recipe API backend, building a minimal frontend, generating a static JSON API, and extending with Schema.org output and the Rust parser library.

The JSON Output

Every .cook file parses to structured JSON with a single command. Given a recipe file like risotto.cook:

cook recipe risotto.cook --format json

The output is a complete structured representation of the recipe:

{
  &#34;name&#34;: &#34;Risotto&#34;,
  &#34;metadata&#34;: {
    &#34;servings&#34;: &#34;4&#34;,
    &#34;time&#34;: &#34;45 minutes&#34;,
    &#34;tags&#34;: &#34;italian, comfort, vegetarian&#34;
  },
  &#34;ingredients&#34;: [
    { &#34;name&#34;: &#34;chicken stock&#34;, &#34;quantity&#34;: &#34;1&#34;, &#34;units&#34;: &#34;litre&#34; },
    { &#34;name&#34;: &#34;butter&#34;, &#34;quantity&#34;: &#34;30&#34;, &#34;units&#34;: &#34;g&#34; },
    { &#34;name&#34;: &#34;shallots&#34;, &#34;quantity&#34;: &#34;2&#34;, &#34;units&#34;: &#34;&#34; },
    { &#34;name&#34;: &#34;arborio rice&#34;, &#34;quantity&#34;: &#34;320&#34;, &#34;units&#34;: &#34;g&#34; },
    { &#34;name&#34;: &#34;dry white wine&#34;, &#34;quantity&#34;: &#34;150&#34;, &#34;units&#34;: &#34;ml&#34; },
    { &#34;name&#34;: &#34;parmesan&#34;, &#34;quantity&#34;: &#34;60&#34;, &#34;units&#34;: &#34;g&#34; }
  ],
  &#34;cookware&#34;: [
    { &#34;name&#34;: &#34;small saucepan&#34; },
    { &#34;name&#34;: &#34;large heavy-bottomed pan&#34; }
  ],
  &#34;steps&#34;: [
    {
      &#34;items&#34;: [
        { &#34;type&#34;: &#34;text&#34;, &#34;value&#34;: &#34;Warm &#34; },
        { &#34;type&#34;: &#34;ingredient&#34;, &#34;name&#34;: &#34;chicken stock&#34;, &#34;quantity&#34;: &#34;1&#34;, &#34;units&#34;: &#34;litre&#34; },
        { &#34;type&#34;: &#34;text&#34;, &#34;value&#34;: &#34; in a &#34; },
        { &#34;type&#34;: &#34;cookware&#34;, &#34;name&#34;: &#34;small saucepan&#34; },
        { &#34;type&#34;: &#34;text&#34;, &#34;value&#34;: &#34; over low heat.&#34; }
      ]
    }
  ]
}

The steps array preserves the inline structure of the original prose — ingredients and cookware appear in context, not just as a flat list. This means you can render step text with ingredient quantities highlighted, the same way Cooklang apps do.

Scaling works too. Pass a serving count with the :N syntax:

cook recipe risotto.cook:2 --format json

All ingredient quantities in the JSON output adjust to the scaled serving count. The API layer is just the command.

The Built-in Server

cook server starts a web interface for browsing your recipe collection:

cook server ./recipes/

This runs at http://localhost:9080 by default and serves the full web UI. But the server also exposes recipe data as JSON through its API endpoints. You can query individual recipes, browse collections, and pull ingredient data programmatically.

The server is a single Rust binary with no database and no configuration. Point it at a directory of .cook files and it works. The server reads files from disk on each request, so adding or editing a recipe is reflected immediately.

For a different port:

cook server ./recipes/ --port 8888

If you're building a frontend that needs live data from your local collection, this is the backend. No setup beyond installing CookCLI.

Building a Static JSON API

For production deployments, you probably want a static JSON API rather than a running server process. A simple shell script turns a folder of .cook files into a directory of JSON files:

#!/bin/bash
# build-api.sh — generates a static JSON API from a recipes directory

RECIPES_DIR=&#34;./recipes&#34;
OUTPUT_DIR=&#34;./api&#34;

mkdir -p &#34;$OUTPUT_DIR&#34;

# Build an index of all recipes
echo &#34;[]&#34; &gt; &#34;$OUTPUT_DIR/index.json&#34;
INDEX=&#34;[]&#34;

for file in &#34;$RECIPES_DIR&#34;/**/*.cook &#34;$RECIPES_DIR&#34;/*.cook; do
    [ -f &#34;$file&#34; ] || continue

    # Derive a slug from the filename
    basename=$(basename &#34;$file&#34; .cook)
    slug=$(echo &#34;$basename&#34; | tr &#39;[:upper:]&#39; &#39;[:lower:]&#39; | tr &#39; &#39; &#39;-&#39;)

    # Parse the recipe to JSON
    cook recipe &#34;$file&#34; --format json &gt; &#34;$OUTPUT_DIR/${slug}.json&#34;

    echo &#34;Built: $slug&#34;
done

echo &#34;Done. JSON files written to $OUTPUT_DIR/&#34;

Run the script after any recipe change and you have a /api/ directory of static JSON files. Serve it with Nginx, GitHub Pages, Netlify, or any static host. No server process, no database — just files.

For CI, add the script to your pipeline. Every push to your recipe repo rebuilds the API automatically.

A Minimal Recipe Frontend

With the JSON API in place, rendering a recipe in a browser takes about thirty lines of JavaScript:

&lt;!DOCTYPE html&gt;
&lt;html lang=&#34;en&#34;&gt;
&lt;head&gt;
  &lt;meta charset=&#34;UTF-8&#34;&gt;
  &lt;title&gt;Recipe&lt;/title&gt;
  &lt;style&gt;
    body { font-family: system-ui, sans-serif; max-width: 680px; margin: 2rem auto; padding: 0 1rem; }
    h1 { margin-bottom: 0.25rem; }
    .meta { color: #666; font-size: 0.9rem; margin-bottom: 1.5rem; }
    .ingredient { font-weight: 600; }
    li { margin-bottom: 0.5rem; }
  &lt;/style&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;div id=&#34;recipe&#34;&gt;&lt;/div&gt;

  &lt;script&gt;
    const slug = new URLSearchParams(window.location.search).get(&#34;recipe&#34;) || &#34;risotto&#34;;

    fetch(`/api/${slug}.json`)
      .then(res =&gt; res.json())
      .then(recipe =&gt; {
        const el = document.getElementById(&#34;recipe&#34;);

        const meta = Object.entries(recipe.metadata || {})
          .map(([k, v]) =&gt; `${k}: ${v}`)
          .join(&#34; · &#34;);

        const ingredients = recipe.ingredients
          .map(i =&gt; `&lt;li&gt;${i.quantity} ${i.units} ${i.name}`.trim() + `&lt;/li&gt;`)
          .join(&#34;&#34;);

        const steps = recipe.steps.map((step, idx) =&gt; {
          const text = step.items.map(item =&gt; {
            if (item.type === &#34;ingredient&#34;) {
              return `&lt;span class=&#34;ingredient&#34;&gt;${item.name}&lt;/span&gt;`;
            }
            return item.value || item.name || &#34;&#34;;
          }).join(&#34;&#34;);
          return `&lt;li&gt;${text}&lt;/li&gt;`;
        }).join(&#34;&#34;);

        el.innerHTML = `
          &lt;h1&gt;${recipe.name}&lt;/h1&gt;
          &lt;p class=&#34;meta&#34;&gt;${meta}&lt;/p&gt;
          &lt;h2&gt;Ingredients&lt;/h2&gt;
          &lt;ul&gt;${ingredients}&lt;/ul&gt;
          &lt;h2&gt;Method&lt;/h2&gt;
          &lt;ol&gt;${steps}&lt;/ol&gt;
        `;
      });
  &lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;

Open recipe.html?recipe=risotto and it fetches /api/risotto.json, renders the ingredient list, and walks through the steps with ingredient names highlighted inline.

This works from any static host. No backend required once you've built the JSON files. Add a second fetch to /api/index.json for a recipe list page, and you have a complete browsable recipe site.

Shopping Lists as JSON

The same JSON flag works for shopping lists:

cook shopping-list --format json risotto.cook pasta-sauce.cook roast-chicken.cook

The output is a combined, deduplicated ingredient list across all three recipes:

{
  &#34;shopping_list&#34;: [
    { &#34;name&#34;: &#34;garlic&#34;, &#34;quantity&#34;: &#34;4&#34;, &#34;units&#34;: &#34;cloves&#34; },
    { &#34;name&#34;: &#34;olive oil&#34;, &#34;quantity&#34;: &#34;60&#34;, &#34;units&#34;: &#34;ml&#34; },
    { &#34;name&#34;: &#34;arborio rice&#34;, &#34;quantity&#34;: &#34;320&#34;, &#34;units&#34;: &#34;g&#34; },
    { &#34;name&#34;: &#34;chicken&#34;, &#34;quantity&#34;: &#34;1.5&#34;, &#34;units&#34;: &#34;kg&#34; }
  ]
}

Matching ingredients from different recipes are combined and quantities summed. This output pipes directly into any frontend that needs a shopping list, or into a grocery integration if you're building one.

With :N scaling per recipe:

cook shopping-list --format json risotto.cook:2 pasta-sauce.cook:6

Each recipe scales independently before the lists merge.

Schema.org Output for SEO

If you're publishing recipes on a public site, structured data matters. Search engines use Schema.org Recipe markup to display cooking times, ingredients, and ratings in search results.

CookCLI generates this directly:

cook recipe risotto.cook --format schema

Output:

{
  &#34;@context&#34;: &#34;https://schema.org&#34;,
  &#34;@type&#34;: &#34;Recipe&#34;,
  &#34;name&#34;: &#34;Risotto&#34;,
  &#34;recipeIngredient&#34;: [
    &#34;1 litre chicken stock&#34;,
    &#34;30 g butter&#34;,
    &#34;320 g arborio rice&#34;,
    &#34;150 ml dry white wine&#34;,
    &#34;60 g parmesan&#34;
  ],
  &#34;recipeInstructions&#34;: [
    {
      &#34;@type&#34;: &#34;HowToStep&#34;,
      &#34;text&#34;: &#34;Warm chicken stock in a small saucepan over low heat. Keep it at a gentle simmer throughout.&#34;
    }
  ],
  &#34;recipeYield&#34;: &#34;4 servings&#34;,
  &#34;totalTime&#34;: &#34;PT45M&#34;
}

Drop this into a <script type="application/ld+json"> tag in your recipe page and search engines can parse the recipe structure directly. Add it to the build script:

# Add to build-api.sh alongside the regular JSON
cook recipe &#34;$file&#34; --format schema &gt; &#34;$OUTPUT_DIR/${slug}.schema.json&#34;

Then include it in your HTML template alongside the regular recipe data.

Other Output Formats

cook recipe supports several other formats you might find useful depending on your use case:

--format yaml — same structure as JSON but YAML, useful if you're feeding into Ansible playbooks or other YAML-native tooling
--format markdown — renders the recipe as formatted Markdown, good for documentation sites or static site generators
--format cooklang — round-trips the recipe back to Cooklang syntax, useful for normalization
--format latex — generates LaTeX output for printable recipe books (pairs with the cookbook PDF scripts covered in the server docs)

For an API use case, JSON and schema are the most useful. YAML is handy if you're generating recipe data for a Hugo or Jekyll site where YAML front matter is expected.

Embedding the Parser Directly

For tighter integration, the cooklang-rs Rust library lets you embed the parser in your own application rather than shelling out to CookCLI:

# Cargo.toml
[dependencies]
cooklang = &#34;0.14&#34;

use cooklang::{CooklangParser, Extensions};

fn main() {
    let parser = CooklangParser::new(Extensions::all());
    let source = std::fs::read_to_string(&#34;risotto.cook&#34;).unwrap();
    let (recipe, _warnings) = parser.parse(&amp;source).into_result().unwrap();

    for ingredient in &amp;recipe.ingredients {
        println!(&#34;{}: {} {}&#34;, ingredient.name, ingredient.quantity, ingredient.unit.as_deref().unwrap_or(&#34;&#34;));
    }
}

This is the same parser CookCLI uses internally. You get full access to the parsed AST — ingredients, steps, metadata, cookware, timers — with no subprocess overhead.

The library also compiles to WebAssembly. The cooklang-rs playground runs it in-browser, which means you can parse .cook files on the client side with zero server round-trips. A recipe editor that parses and validates as you type is a straightforward WASM integration.

For other languages, there are parser libraries in Python, TypeScript, Go, Swift, and others. The full list is at /docs/for-developers/.

What You End Up With

Putting this together, the full stack looks like:

.cook files as the source of truth — version-controlled, plain text, human-readable
A build script that runs cook recipe --format json on each file and writes to /api/
A static frontend that fetches from /api/ and renders recipe pages
Schema.org JSON-LD embedded in each page for search engine structured data
The CookCLI server for local development and in-kitchen browsing

No third-party API keys. No rate limits. No data locked in someone else's schema. The files are yours, the API is yours, and the whole stack runs on a $5 VPS or a Raspberry Pi.

The CookCLI documentation at /cli/ covers every flag. If you want to understand the Cooklang format itself before writing recipes programmatically, the spec at /docs/spec/ is the canonical reference.

Get started with Cooklang →

-Alex