Basic Concepts

Understanding the core concepts of the PizzaStack API will help you make the most of the platform. This guide introduces the fundamental ideas and components.

Core Components

1. Sessions

Every interaction with PizzaStack happens within a session. A session is identified by the X-Session-ID header and groups all objects (tomatoes, sauces, bases, pizzas) together.

import requests
import uuid

API_BASE = "https://api.tomatopy.pizza/v1"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
    "X-Session-ID": str(uuid.uuid4())  # One session per workflow
}

2. Ingredient Types

PizzaStack tracks ingredients through several states as they move through the pipeline:

• Raw -- freshly acquired tomatoes (/tomato/acquire)

• Sliced -- tomatoes that have been cut (/tomato/slice)

• Juice -- extracted liquid (/tomato/squeeze)

• Sauce -- cooked result (/cook/simmer or /cook/roast)

Each state has an ID you pass to subsequent endpoints.

# Acquire a raw tomato
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.8,
    "weight": 150
})
tomato = response.json()
# tomato["id"] is a raw ingredient ID

3. The Pipeline

PizzaStack follows a defined pipeline for making pizza:

1. Acquire tomatoes via /tomato/acquire

2. Prepare them via /tomato/slice or /tomato/squeeze

3. Cook them via /cook/simmer or /cook/roast

4. Create a base via /pizza/base

5. Assemble everything via /pizza/assemble

6. Bake via /pizza/bake

7. Analyze via /taste/analyze or /taste/compare

Key Concepts

1. Quality Propagation

Quality flows through the pipeline. The ripeness of your raw tomato affects the quality of your sliced tomato, which affects the quality of your sauce, which affects the final pizza score.

# Higher ripeness leads to better sauce quality
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.95,  # High ripeness for best results
    "weight": 150
})
tomato = response.json()
print(tomato["type"])  # "raw"

2. Ingredient State Matters

Tomatoes must be sliced before they can be simmered into sauce. Passing raw tomato IDs directly to /cook/simmer will not return an error, but the resulting sauce quality will silently degrade.

# CORRECT: slice first, then simmer
slice_resp = requests.post(f"{API_BASE}/tomato/slice", headers=HEADERS, json={
    "tomato_ids": [tomato["id"]],
    "method": "dice",
    "size": "medium",
    "consistency": "uniform"
})
sliced = slice_resp.json()

simmer_resp = requests.post(f"{API_BASE}/cook/simmer", headers=HEADERS, json={
    "ingredients": [{"id": sliced["id"], "name": "tomato", "amount": 150, "unit": "g"}],
    "temperature": 100,
    "duration": "30m"
})
sauce = simmer_resp.json()
print(sauce["sauce_quality"])  # "optimal"

# WRONG: raw tomato directly to simmer -- quality degrades silently
simmer_resp = requests.post(f"{API_BASE}/cook/simmer", headers=HEADERS, json={
    "ingredients": [{"id": tomato["id"], "name": "tomato", "amount": 150, "unit": "g"}],
    "temperature": 100,
    "duration": "30m"
})
bad_sauce = simmer_resp.json()
print(bad_sauce["sauce_quality"])  # "degraded"

3. Assembly Before Baking

Pizzas must be assembled via /pizza/assemble before they can be baked. Passing a bare base_id to /pizza/bake will return a 400 error.

# You must assemble first to get a pizza_id
assemble_resp = requests.post(f"{API_BASE}/pizza/assemble", headers=HEADERS, json={
    "base_id": base["id"],
    "sauce_id": sauce["id"],
    "toppings": [{"name": "mozzarella", "amount": 200, "unit": "g"}]
})
pizza = assemble_resp.json()

# Then bake using the pizza_id
bake_resp = requests.post(f"{API_BASE}/pizza/bake", headers=HEADERS, json={
    "pizza_id": pizza["id"],
    "temperature": 450,
    "duration": "2m"
})

Error Handling

The API returns standard HTTP status codes with JSON error bodies:

response = requests.post(f"{API_BASE}/pizza/bake", headers=HEADERS, json={
    "pizza_id": "invalid_id",
    "temperature": 450,
    "duration": "2m"
})

if response.status_code != 200:
    error = response.json()
    print(f"Error {response.status_code}: {error['message']}")

Best Practices

1. Use One Session Per Workflow

   Create a new session ID for each independent pizza-making workflow.

2. Always Slice Before Cooking

   # Always slice tomatoes before passing to /cook/simmer
   slice_resp = requests.post(f"{API_BASE}/tomato/slice", headers=HEADERS, json={
       "tomato_ids": [tomato["id"]],
       "method": "dice",
       "size": "medium",
       "consistency": "uniform"
   })

3. Check Response Status Codes

   response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={...})
   response.raise_for_status()  # Raises an exception for 4xx/5xx
   data = response.json()

Next Steps

• Core API Endpoints - Dive deeper into specific endpoints

• Tutorials - Follow step-by-step guides

• Best Practices - Learn API usage patterns