wger API响应格式：使用JSON Schema验证健身数据响应

wger API响应格式：使用JSON Schema验证健身数据响应

【免费下载链接】wger Self hosted FLOSS fitness/workout, nutrition and weight tracker written with Django 项目地址: https://gitcode.com/GitHub_Trending/wg/wger

还在为健身应用API响应格式不一致而烦恼吗？wger项目提供了一套完整的REST API响应规范，通过JSON Schema确保数据格式的统一性和可靠性。本文将详细介绍wger API的响应格式规范，并展示如何使用JSON Schema进行数据验证。

wger API响应结构解析

wger采用标准的Django REST Framework（DRF）序列化器来定义API响应格式。以用户资料API为例，响应包含完整的用户信息字段：

{
  "username": "user@example.com",
  "email": "user@example.com",
  "email_verified": true,
  "is_trustworthy": false,
  "date_joined": "2024-01-01T00:00:00Z",
  "gym": null,
  "weight_rounding": 0.25,
  "repetitions_rounding": 1,
  "is_temporary": false,
  "show_comments": true,
  "show_english_ingredients": false,
  "workout_reminder_active": false,
  "workout_reminder": 19,
  "workout_duration": 60,
  "last_workout_notification": null,
  "notification_language": 1,
  "age": 30,
  "birthdate": "1994-01-01",
  "height": 175,
  "gender": "male",
  "sleep_hours": 8,
  "work_hours": 8,
  "work_intensity": "medium",
  "sport_hours": 5,
  "sport_intensity": "high",
  "freetime_hours": 3,
  "freetime_intensity": "low",
  "calories": 2500,
  "weight_unit": 1,
  "ro_access": false,
  "num_days_weight_reminder": 7
}

核心序列化器定义

wger使用DRF ModelSerializer来定义API响应结构。用户资料序列化器位于wger/core/api/serializers.py：

class UserprofileSerializer(serializers.ModelSerializer):
    email = serializers.EmailField(source='user.email', read_only=True)
    username = serializers.EmailField(source='user.username', read_only=True)
    date_joined = serializers.EmailField(source='user.date_joined', read_only=True)

    class Meta:
        model = UserProfile
        fields = (
            'username', 'email', 'email_verified', 'is_trustworthy',
            'date_joined', 'gym', 'weight_rounding', 'repetitions_rounding',
            'is_temporary', 'show_comments', 'show_english_ingredients',
            'workout_reminder_active', 'workout_reminder', 'workout_duration',
            'last_workout_notification', 'notification_language', 'age',
            'birthdate', 'height', 'gender', 'sleep_hours', 'work_hours',
            'work_intensity', 'sport_hours', 'sport_intensity', 'freetime_hours',
            'freetime_intensity', 'calories', 'weight_unit', 'ro_access',
            'num_days_weight_reminder'
        )

语言和认证API响应

语言API提供多语言支持，响应格式定义在LanguageSerializer：

{
  "id": 1,
  "short_name": "en",
  "full_name": "English",
  "full_name_en": "English"
}

认证API使用专门的序列化器处理登录和注册，确保安全性：

// 登录成功响应
{
  "token": "abc123def456ghi789"
}

// 注册成功响应  
{
  "message": "api user successfully registered",
  "token": "xyz789uvw456rst123"
}

使用JSON Schema进行验证

wger API支持JSON Schema验证，确保客户端接收的数据格式正确。以下是一个验证用户资料响应的JSON Schema示例：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "username": {"type": "string", "format": "email"},
    "email": {"type": "string", "format": "email"},
    "email_verified": {"type": "boolean"},
    "height": {"type": "integer", "minimum": 100, "maximum": 250},
    "weight_unit": {"type": "integer"},
    "birthdate": {"type": "string", "format": "date"}
  },
  "required": ["username", "email", "email_verified"]
}

错误响应格式

wger API提供统一的错误响应格式，便于客户端处理异常情况：

{
  "detail": "Username or password unknown",
  "code": "authentication_failed"
}

{
  "check": {
    "result": false,
    "detected_language": "de",
    "message": "The detected language is German (de), which does not match your selected language English (en)"
  }
}

最佳实践建议

1. 字段一致性：所有API响应使用相同的字段命名约定
2. 类型安全：严格定义字段数据类型，避免类型混淆
3. 版本控制：API响应格式随版本更新而演进，保持向后兼容
4. 文档化：使用OpenAPI规范文档化所有API端点

通过遵循wger的API响应格式规范，您可以构建健壮的健身应用集成，确保数据交换的可靠性和一致性。

【免费下载链接】wger Self hosted FLOSS fitness/workout, nutrition and weight tracker written with Django 项目地址: https://gitcode.com/GitHub_Trending/wg/wger