API Usage Best Practices

This guide covers best practices for using the PizzaStack API efficiently and correctly.

Error Handling

Always Check Response Status

import requests

API_BASE = "https://api.tomatopy.pizza/v1"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
    "X-Session-ID": "your-session-id"
}

# GOOD: Check status and handle errors
response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
    "variety": "San Marzano",
    "ripeness": 0.8,
    "weight": 150
})

if response.status_code == 200:
    tomato = response.json()
elif response.status_code == 400:
    print(f"Bad request: {response.json()['message']}")
elif response.status_code == 401:
    print("Invalid API key")
else:
    print(f"Unexpected error: {response.status_code}")

Use raise_for_status()

For simpler scripts, use raise_for_status() to throw exceptions on errors:

# GOOD: Exceptions on error
try:
    response = requests.post(f"{API_BASE}/tomato/acquire", headers=HEADERS, json={
        "variety": "San Marzano",
        "ripeness": 0.8,
        "weight": 150
    })
    response.raise_for_status()
    tomato = response.json()
except requests.exceptions.HTTPError as e:
    print(f"API error: {e}")
except requests.exceptions.ConnectionError:
    print("Could not connect to API")

Create a Helper Function

Reduce boilerplate with a wrapper:

def api_post(endpoint, payload):
    """Make a POST request to the PizzaStack API with error handling."""
    response = requests.post(f"{API_BASE}{endpoint}", headers=HEADERS, json=payload)
    response.raise_for_status()
    return response.json()

# Usage
tomato = api_post("/tomato/acquire", {
    "variety": "San Marzano",
    "ripeness": 0.8,
    "weight": 150
})

Checking Response Quality Fields

Sauce responses include a sauce_quality field. Always check it to catch pipeline issues early.

# GOOD: Check quality at each step
tomato = api_post("/tomato/acquire", {
    "variety": "San Marzano", "ripeness": 0.9, "weight": 400
})
print(f"Tomato type: {tomato['type']}")

sliced = api_post("/tomato/slice", {
    "tomato_ids": [tomato["id"]], "method": "dice",
    "size": "medium", "consistency": "uniform"
})

sauce = api_post("/cook/simmer", {
    "ingredients": [{"id": sliced["id"], "name": "tomato", "amount": 400, "unit": "g"}],
    "temperature": 100, "duration": "30m"
})

# Catch quality degradation early
if sauce["sauce_quality"] == "degraded":
    print("WARNING: Sauce quality is low. Did you slice the tomatoes first?")

Validating Pipeline Order

The PizzaStack pipeline has strict ordering requirements. Two key rules to follow:

Rule 1: Slice Before Simmering

Raw tomato IDs passed to /cook/simmer will not cause an error, but the sauce quality will silently degrade.

# GOOD: Slice first
sliced = api_post("/tomato/slice", {
    "tomato_ids": [tomato["id"]],
    "method": "dice",
    "size": "medium",
    "consistency": "uniform"
})
sauce = api_post("/cook/simmer", {
    "ingredients": [{"id": sliced["id"], "name": "tomato", "amount": 400, "unit": "g"}],
    "temperature": 100,
    "duration": "30m"
})

# BAD: Skip slicing -- quality degrades silently
sauce = api_post("/cook/simmer", {
    "ingredients": [{"id": tomato["id"], "name": "tomato", "amount": 400, "unit": "g"}],
    "temperature": 100,
    "duration": "30m"
})
# sauce["sauce_quality"] will be "degraded"

Rule 2: Assemble Before Baking

Passing a base_id to /pizza/bake returns a 400 error. You must assemble first.

# GOOD: Assemble then bake
pizza = api_post("/pizza/assemble", {
    "base_id": base["id"],
    "sauce_id": sauce["id"],
    "toppings": [{"name": "mozzarella", "amount": 200, "unit": "g"}]
})
baked = api_post("/pizza/bake", {
    "pizza_id": pizza["id"],
    "temperature": 450,
    "duration": "2m"
})

# BAD: Try to bake a base directly -- returns 400
try:
    baked = api_post("/pizza/bake", {
        "pizza_id": base["id"],  # Wrong! This is a base_id
        "temperature": 450,
        "duration": "2m"
    })
except requests.exceptions.HTTPError as e:
    print(f"Error: {e}")  # 400 Bad Request

Reusing Session IDs Correctly

Do: Use the Same Session for Related Operations

import uuid

# All operations in one pizza workflow share a session
session_id = str(uuid.uuid4())
HEADERS["X-Session-ID"] = session_id

tomato = api_post("/tomato/acquire", {...})
sliced = api_post("/tomato/slice", {"tomato_ids": [tomato["id"]], ...})
sauce = api_post("/cook/simmer", {"ingredients": [{"id": sliced["id"], ...}], ...})
# All objects are in the same session and can reference each other

Do Not: Mix Unrelated Workflows in One Session

# BAD: Two unrelated pizzas in one session creates confusion
marinara_tomato = api_post("/tomato/acquire", {"variety": "San Marzano", ...})
pesto_basil = api_post("/tomato/acquire", {"variety": "Roma", ...})
# Which tomato goes with which pizza? Hard to track.

Do Not: Change Session ID Mid-Workflow

# BAD: Changing session mid-workflow breaks references
HEADERS["X-Session-ID"] = str(uuid.uuid4())
tomato = api_post("/tomato/acquire", {...})

HEADERS["X-Session-ID"] = str(uuid.uuid4())  # New session!
sliced = api_post("/tomato/slice", {
    "tomato_ids": [tomato["id"]],  # This ID is from the old session -- will fail
    ...
})

Retry Logic

For production use, add retry logic for transient errors:

import time

def api_post_with_retry(endpoint, payload, max_retries=3):
    """Make API call with retry logic for transient errors."""
    for attempt in range(max_retries):
        try:
            response = requests.post(
                f"{API_BASE}{endpoint}",
                headers=HEADERS,
                json=payload,
                timeout=30
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.ConnectionError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except requests.exceptions.HTTPError as e:
            if response.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

Best Practices Summary

1. Always handle errors -- check status codes or use raise_for_status()

2. Check quality fields -- catch pipeline issues before they cascade

3. Follow pipeline order -- slice before simmer, assemble before bake

4. One session per workflow -- do not mix unrelated operations

5. Keep session IDs consistent -- do not change mid-workflow

6. Add retry logic for production applications

7. Use a helper function to reduce boilerplate

Next Steps

• Session Management Best Practices - Session lifecycle and debugging

• Core API Endpoints - Endpoint reference

• Tutorials - End-to-end examples