Recipe API Design Guide
Patterns for building intuitive, predictable, and maintainable APIs that developers love to use.
Resource Naming
Use plural nouns for collections. Keep URLs predictable with a consistent hierarchy. Prefer kebab-case over camelCase or snake_case in path segments.
GET /recipes/chocolate-cake
POST /recipes
PATCH /recipes/chocolate-cake
Versioning Strategy
Version via the URL path prefix. Avoid header-based versioning for public APIs — it hides discoverability and complicates debugging.
GET /v2/recipes?include=nutrition
Error Responses
Return consistent error shapes. Always include a machine-readable code and a human-readable message. Use standard HTTP status codes.
"error": {
"code": "RECIPE_NOT_FOUND",
"message": "No recipe with slug chocolate-cake exists"
}
}
Pagination
Use cursor-based pagination for large datasets. Return a next cursor and a has_more flag so clients can iterate without counting total rows.
This guide reflects patterns used across Meridian's own public APIs. Read the API reference for endpoint-specific details.