Mealie食谱管理系统的API使用指南

前言

Mealie作为一款现代化的食谱管理系统，提供了丰富的API接口供开发者进行二次开发和系统集成。本文将详细介绍Mealie API的核心功能和使用方法，帮助开发者快速掌握API的使用技巧。

API认证与授权

获取API令牌

1. 登录Mealie系统后，进入用户个人资料页面
2. 导航至API令牌管理界面
3. 创建长期有效的API令牌
4. 妥善保管生成的令牌，它将作为API调用的身份凭证

API核心功能详解

交互式API文档

Mealie提供了内置的交互式API文档，开发者可以通过以下方式访问：

1. 本地部署环境下访问/docs路径
2. 文档提供完整的接口描述和示例
3. 支持直接测试API并查看返回结果
4. 包含cURL命令示例，便于快速集成

扩展功能(Extras)

食谱扩展

食谱扩展是Mealie API的特色功能，允许开发者：

1. 为食谱添加自定义的JSON键值对
2. 支持第三方应用集成
3. 可用于触发自动化流程
4. 示例：添加提醒信息{"message": "记得提前解冻鸡肉"}

购物清单和食品扩展

1. 购物清单和食品同样支持扩展属性
2. 目前仅能通过API访问这些扩展
3. 可实现与第三方清单管理工具的深度集成

典型应用场景：

• 同步Trello清单ID：{"trello_list_id": "5abbe4b7ddc1b351ef961414"}
• 跟踪单个卡片：{"trello_card_id": "bab414bde415cd715efb9361"}
• 排除特定食品：{"trello_exclude_food": "true"}

数据查询与分页

分页机制

Mealie API采用标准分页设计：

1. perPage参数控制每页返回的记录数
2. page参数指定当前页码
3. 响应中包含分页导航信息
4. 特殊值：
   • perPage = -1：返回所有结果
   • page = -1：返回最后一页

示例响应：

{
  "page": 2,
  "per_page": 5,
  "total": 23,
  "total_pages": 5,
  "data": [...],
  "next": "/recipes?page=3&per_page=5",
  "previous": "/recipes?page=1&per_page=5"
}

高级过滤查询

Mealie提供强大的过滤功能：

基础过滤

1. 等值查询：name = "Pasta Fagioli"
2. 范围查询：createdAt >= "2021-02-22"
3. 布尔查询：useAbbreviation = false
4. 不等查询：name <> "carrot"

关键字过滤

1. 空值检查：lastMade IS NOT NULL
2. 模糊匹配：name NOT LIKE "Test%"
3. 包含检查：slug IN ["pasta-fagioli", "delicious-ramen"]

嵌套属性过滤

1. 关联表查询：user.username = "SousChef20220320"
2. 多级关联：recipe.createdAt >= "2023-02-25"
3. 标签查询：tags.name CONTAINS ALL ["Easy", "Cajun"]

复合过滤

1. 逻辑组合：name = "A" OR name = "B"
2. 多条件：createdAt < "2014-01-02" AND name <> "Ramen"
3. 分组过滤：(条件A AND 条件B) OR 条件C

高级排序

1. 多字段排序：lastMade, createdAt
2. 排序方向：
   • 全局设置：orderDirection=asc|desc
   • 字段级设置：lastMade:asc, createdAt:desc
3. 空值处理：orderByNullPosition=first|last
4. 关联表排序：label.name

最佳实践建议

1. 合理使用分页，避免一次性获取大量数据
2. 复杂查询建议先在小数据集上测试
3. 注意日期格式的兼容性
4. 充分利用扩展属性实现业务定制
5. 定期轮换API令牌保证安全性

通过掌握这些API功能，开发者可以充分发挥Mealie的潜力，构建个性化的食谱管理解决方案。