Welsh Academy

Version Française

Welsh Academy is an application dedicated to provide recipes to cheddar lovers around the world. This a backend allowing cheddar experts to:

• Create ingredients
• Create recipes of meals using the previously created ingredients

A user should be able to enjoy the recipes by using the API to:

• list all existing ingredients
• list all possible recipes (with or without ingredient constraints)
• flag/unflag recipes as his favorite ones
• list his favorite recipes

Table of contents

• Tables of endpoints
• Entity/Model design
  • User
  • Ingredient
  • Recipe
  • Favorite Recipe
• API Usage
  • /ingredients
  • /recipes
  • /users/:uid/favorites
• Running
  • With docker
  • Without docker
• Testing

Table of endpoints

Method	URL Pattern	Handler	Action
GET	/		Display a welcome message
GET	/ingredients	listIngredients	List all existing ingredients
POST	/ingredients	createIngredient	Create a new ingredient (expert only)
GET	/recipes?include=1,2&exclude=3,4	listRecipes	List all existing recipes
POST	/recipes	createRecipe	Create a new recipe (expert only)
GET	/users/:uid/favorites	listFavorites	List all favorite recipes of an user with id "uid"
POST	/users/:uid/favorites	flagFavoriteRecipe	Flag/Add a recipe as user favorite one
DELETE	/users/:uid/favorites/:fid	unflagFavoriteRecipe	Unflag/Remove favorite with id "fid"

Entity/Model Design

User

User is supposed to be managed by another api, but here I would like to have a simple structure of an user

Field	ID	Username	Role
Type	Integer	String	Expert/User

Ingredient

Field	ID	Name	CreatorId	Created
Type	Integer	String	Integer	Time

Recipe

SubType(RecipeIngredient)

Field	ID(IngredientID)	Amount	Unit
Type	Integer	Float	String (ml/g/l/kg/...)

Recipe

Field	ID	CreatorId	Name	Ingredients	Description	Created
Type	Integer	Integer	String	[]RecipeIngredient	String	Created

Favorite Recipe

Field	ID	UserId	RecipeId
Type	Integer	Integer	Integer

API Usage

/ingredients

GET /ingredients

POST /ingredient with body

{
  "name": "Tomato",
  "creator_id": 3
}

/recipes

GET /recipes
GET /recipes?include=1
GET /recipes?include=1,2
GET /recipes?exclude=1,2
GET /recipes?include=1,3&exclude=2

POST /recipes with body

{
  "name": "Name of recipe",
  "description": "Some details, steps, bla... description",
  "creator_id": 3,
  "ingredients": {
    "1": {
      "amount": 0.5,
      "unit": "bow"
    },
    "2": {
      "amount": 1,
      "unit": "spoon"
    },
    "3": {
      "amount": 100,
      "unit": "g"
    }
  }
}

/users/:uid/favorites

GET /users/1/favorites
GET /users/2/favorites

POST /users/1/favorites
with body

{
  "recipe_id": 1
}

DELETE /users/1/favorites/1

Running

With docker

We need three environnement variables : POSTGRES_PASSWORD,POSTGRES_DB and PORT.

• POSTGRES_PASSWORD to set password for default postgres user, be default "azerty"
• POSTGRES_DB for the database name, by default "welsh"
• PORT on which the api is exposed, by default 8000

For example:

• POSTGRES_PASSWORD=i-cannot-be-broken
• POSTGRES_DNS=welsh-academy
• PORT=5000

First go to the root project directory

cd ./path/to/root/of/project

With default password and db name:

docker compose -f ./docker/docker-compose.yml up

With custom password, db name and port:

POSTGRES_PASSWORD=your-password POSTGRES_DB=you-db-name PORT=your-port-number docker compose -f ./docker/docker-compose.yml up

And that, api will be available on localhost:8000 (or your port)

Without docker

First run migrations (only for the first time running app)

go run ./cmd/cli/migrate -dns=your_postgres_dns -up

Run the app

go run ./cmd/api -db-dns=your__postgres_dns -port=your_port

Testing

Test API handlers

CGO_ENABLED=0 go test ./cmd/api

Testing DB models (mock)

go test ./internal/models/

Testing with postgres (test db) inside containers

docker compose -f ./docker/docker-compose.test.yml up --build

And then test results should appear in logger.