# Beelong - Calculateur - API : Get HealthScore
###### tags: `Beelong` `API` `Calculateur` `Technical Documentation`

[TOC]

## 1. Introduction

This API specification aims to provide the client an external solution to retrieve his recipes and menus Health-Scores. The business reason is to allow the client to take advantage of the Health-Score methodology, without using the Calculator interface.

## 2. Prerequisite

Beelong will provide to the client, for each environment (staging/prod):
- a personal token

## 3. GraphQL schema

type Query {
  clientRecipeHealthScore(recipe: ClientRecipe!, age: EnumAge!): HealthScore
  clientMenuHealthScore(menu: ClientMenu!, age: EnumAge!): HealthScore
}

enum EnumAge {
  Senior
  Adult
  From16to20
  From13to15
  From7to12
  From4to6
  From2to3
  From0to1
}

enum EnumMealType {
  Starter
  Main_dish
  Side_dish
  Dessert_snack
  Subrecipe
}

enum Acceptability {
  GOOD
  ACCEPTABLE
  BAD
}

input ClientMenu {
  recipes: [ClientRecipe!]!
}

input ClientRecipe {
  mealType: EnumMealType!
  nbPortions: Int!
  products: [ClientProduct!]!
}

input ClientProduct {
  productUuid: String!

  # Product quantity in the recipe (grams)
  quantity: Int!
}

type HealthScore {
  grade: NutriGrade!
  score: Float
  optimalTrim: OptimalTrimDistribution
  nutritionalComposition: NutritionalCompositionProportionAndAcceptability
}

type NutriGrade {
  grade: HealthGrade!
  imageUrl: String
}

type OptimalTrimDistribution {
  proteinFoodQuantity: Float!
  proteinFoodPercentage: Float!
  proteinFoodIsAcceptable: Boolean!
  starchyQuantity: Float!
  starchyPercentage: Float!
  starchyIsAcceptable: Boolean!
  vegetablesQuantity: Float!
  vegetablesPercentage: Float!
  vegetablesIsAcceptable: Boolean!
  addedFatQuantity: Float!
  addedFatPercentage: Float!
  addedFatIsAcceptable: Boolean!
}

type NutritionalCompositionProportionAndAcceptability {
  fibers: ProportionAndAcceptability!
  sfa: ProportionAndAcceptability!
  sodium: ProportionAndAcceptability!
}

type ProportionAndAcceptability {
  proportion: Float!
  acceptability: Acceptability!
}

## 4. Technologies

The API language is GraphQL. JSON will be used for the request payload.

## 5. Example

A testing establishement can be setup, on **staging** environment, to provide the best and complete experience for the testers of this API.

All data from this example can be used as-is to access the testing establishment, except for the token which will be provided by Beelong.

#### 5.1 GraphQL header (example)

A token is required for every HTTPS request.
**The same token can be used for both requests (recipe and menu health-score).**

Example:

x-api-key client@1N4fnskfk8djsN8j

:warning: This is only provided for demonstration purpose.

### 5.2 The request: get recipe Health-Score

URL of the API (staging): https://api.secure.staging.beelong.ch/graphql
URL of the API (prod): https://api.secure.beelong.ch/graphql

#### 5.2.1 Query

query ($recipe: ClientRecipe!, $age: EnumAge!) {
  clientRecipeHealthScore(recipe: $recipe, age: $age) {
    grade {
        grade
        imageUrl
    }
    score
    optimalTrim {
        proteinFoodQuantity
        proteinFoodPercentage
        proteinFoodIsAcceptable
        vegetablesQuantity
        vegetablesPercentage
        vegetablesIsAcceptable
        starchyQuantity
        starchyPercentage
        starchyIsAcceptable
        addedFatQuantity
        addedFatPercentage
        addedFatIsAcceptable
    }
    nutritionalComposition {
        fibers {
            proportion
            acceptability
        }
        sfa {
            proportion
            acceptability
        }
        sodium {
            proportion
            acceptability
        }
    }
  }
}

> **NOTE**: optimalTrim and nutritionalComposition aren't available for **Dessert_snack** recipes

#### 5.2.2 GraphQL variables

{ 
  "recipe": {
    "mealType": "Dessert_snack",
    "nbPortions": 1,
    "products": [
        { "productUuid": "5d9461d02fa18", "quantity": 2000 },
        { "productUuid": "5d9461d0450bd", "quantity": 500 }
    ]
  },
  "age": "Adult"
}

###### productUuid

The productUuid comes from the generated product by Beelong's eco-scoring process

#### 5.2.3 The response

{
    "data": {
        "clientRecipeHealthScore": {
            "grade": {
                "grade": "C",
                "imageUrl": "https://api.public.staging.beelong.ch/image/nutrigrade/C"
            },
            "score": 60.92,
            "optimalTrim": null,
            "nutritionalComposition": null
        }
    }
}

### 5.3 The request: get menu Health-Score

URL of the API (staging): https://api.secure.staging.beelong.ch/graphql
URL of the API (prod): https://api.secure.beelong.ch/graphql

#### 5.3.1 Query

query ($menu: ClientMenu!, $age: EnumAge!) {
  clientMenuHealthScore(menu: $menu, age: $age) {
    grade {
        grade
        imageUrl
    }
    score
    optimalTrim {
        proteinFoodQuantity
        proteinFoodPercentage
        proteinFoodIsAcceptable
        vegetablesQuantity
        vegetablesPercentage
        vegetablesIsAcceptable
        starchyQuantity
        starchyPercentage
        starchyIsAcceptable
        addedFatQuantity
        addedFatPercentage
        addedFatIsAcceptable
    }
    nutritionalComposition {
        fibers {
            proportion
            acceptability
        }
        sfa {
            proportion
            acceptability
        }
        sodium {
            proportion
            acceptability
        }
    }
  }
}

> **NOTE**: optimalTrim and nutritionalComposition aren't available for menus composed only of **Dessert_snack** recipes

#### 5.3.2 GraphQL variables

{ 
    "menu": {
        "recipes": [
            {
                "mealType": "Main_dish",
                "nbPortions": 10,
                "products": [
                    { "productUuid": "5df1025e4dba8", "quantity": 50 },
                    { "productUuid": "5df1026157f80", "quantity": 400 },
                    { "productUuid": "5ee9dc99d4484", "quantity": 20 },
                    { "productUuid": "5ff48d3a33666", "quantity": 500 },
                    { "productUuid": "6130f6af87962", "quantity": 500 },
                    { "productUuid": "6130f6e7159f6", "quantity": 10 },
                    { "productUuid": "6130f6ebe942b", "quantity": 15 },
                    { "productUuid": "6130f7406fcf7", "quantity": 500 },
                    { "productUuid": "618018036b395", "quantity": 1000 },
                    { "productUuid": "61815925f2f9d", "quantity": 50 }
                ]
            },
            {
                "mealType": "Dessert_snack",
                "nbPortions": 1,
                "products": [
                    { "productUuid": "5ee9d84790f17", "quantity": 10 },
                    { "productUuid": "5ee9eba92b7e3", "quantity": 25 },
                    { "productUuid": "618015b124288", "quantity": 17 },
                    { "productUuid": "6180167d47914", "quantity": 14 },
                    { "productUuid": "618018a4984af", "quantity": 9 },
                    { "productUuid": "618018da9db30", "quantity": 30 }
                ]
            }
        ]
    },
    "age": "Adult"
}

#### 5.3.3 The response

{
    "data": {
        "clientMenuHealthScore": {
            "grade": {
                "grade": "C",
                "imageUrl": "https://api.public.staging.beelong.ch/image/nutrigrade/C"
            },
            "score": 60.75801749271137,
            "optimalTrim": {
                "proteinFoodQuantity": 30,
                "proteinFoodPercentage": 25,
                "proteinFoodIsAcceptable": false,
                "vegetablesQuantity": 487,
                "vegetablesPercentage": 136.68,
                "vegetablesIsAcceptable": true,
                "starchyQuantity": 10,
                "starchyPercentage": 22.22,
                "starchyIsAcceptable": false,
                "addedFatQuantity": 19,
                "addedFatPercentage": 150,
                "addedFatIsAcceptable": false
            },
            "nutritionalComposition": {
                "fibers": {
                    "proportion": 4.832722832722832,
                    "acceptability": "GOOD"
                },
                "sfa": {
                    "proportion": 3.3113553113553116,
                    "acceptability": "BAD"
                },
                "sodium": {
                    "proportion": 280.5250305250305,
                    "acceptability": "ACCEPTABLE"
                }
            }
        }
    }
}