csep-2025/docs/recipe-api.md

Recipe API

Base path: /api

This API allows clients to create, read, update, and delete Recipe resources.

---

Endpoints

Get a Recipe by ID

GET /api/recipe/{id}

Retrieves a specific recipe by its unique identifier.

• Path Parameters

  Name	Type	Required	Description
  id	Long	Yes	The ID of the recipe to fetch.

• Responses

  Status Code	Description
  200 OK	Returns the recipe with the given ID.
  404 Not Found	No recipe exists with that ID.

• Example Request

  curl -X GET "http://SERVER_ADDRESS/api/recipe/1" \
       -H "Accept: application/json"
  

• Example Response (200)

  {
    "id": 1,
    "name": "Pancakes",
    "ingredients": ["Ingredient 1", "Ingredient 2"],
    "preparationSteps": ["Step 1", "Step 2"]
  }
  

---

List Recipes

GET /api/recipes

Retrieves a list of recipes. Supports optional pagination via a limit query parameter.

• Query Parameters

  Name	Type	Required	Description
  limit	Integer	No	Maximum number of recipes to return. If not provided, returns all recipes.

• Responses

  Status Code	Description
  200 OK	Returns a list of recipes (possibly limited).

• Example Request (no limit)

  curl -X GET "http://SERVER_ADDRESS/api/recipes" \
       -H "Accept: application/json"
  

• Example Request (with limit)

  curl -X GET "http://SERVER_ADDRESS/api/recipes?limit=10" \
       -H "Accept: application/json"
  

• Example Response (200)

  [
    {
      "id": 10,
      "name": "Recipe 0",
      "ingredients": ["Flour", "Milk"],
      "preparationSteps": ["Do something", "Do something else"]
    },
    {
      "id": 11,
      "name": "Recipe 1",
      "ingredients": ["Flour", "Milk"],
      "preparationSteps": ["Do something", "Do something else"]
    }
    // etc. max {limit} items
  ]
  

---

Create a New Recipe

PUT /api/recipe/new

Creates a new recipe. The recipe name must be unique in the repository.

• Request Body

  A JSON object representing the recipe. Example:

  {
    "name": "Pancakes",
    "ingredients": ["Flour", "Milk", "Eggs"],
    "preparationSteps": ["Step 1", "Step 2"]
  }
  

• Responses

  Status Code	Description
  200 OK	The recipe was successfully created. Returns the created recipe (including its assigned ID).
  400 Bad Request	A recipe with the same name already exists.

• Example Request

  curl -X PUT "https://SERVER_ADDRESS/api/recipe/new" \
       -H "Content-Type: application/json" \
       -d '{
             "name": "Pancakes",
             "ingredients": ["Flour", "Milk", "Eggs"],
             "preparationSteps": ["Step 1", "Step 2"]
           }'
  

• Example Response (200)

  {
    "id": 125,
    "name": "Pancakes",
    "ingredients": ["Flour", "Milk", "Eggs"],
    "preparationSteps": ["Step 1", "Step 2"]
  }
  

---

Update an Existing Recipe

POST /api/recipe/{id}

Replaces or updates the recipe with the given ID.

• Path Parameters

  Name	Type	Required	Description
  id	Long	Yes	The ID of the recipe to update.

• Request Body

  A JSON object containing the new recipe data. It is expected to include the ID (or the server-side save will override it), or at least map correctly to the stored entity.

  Example:

  {
    "id": 123,
    "name": "Better Pancakes",
    "ingredients": ["Flour", "Almond milk", "Eggs"],
    "preparationSteps": ["Step 10", "Step 11"]
  }
  

• Responses

  Status Code	Description
  200 OK	The recipe was successfully updated. Returns the updated recipe.
  400 Bad Request	No recipe exists with the given ID.

  • Example Request

    curl -X POST "https://your-domain.com/api/recipe/123" \
         -H "Content-Type: application/json" \
         -d '{
              "id": 123,
              "name": "Better Pancakes",
              "ingredients": ["Flour", "Almond milk", "Eggs"],
              "preparationSteps": ["Step 10", "Step 11"]
            }'
    

• Example Response (200)

  {
    "id": 123,
    "name": "Updated Pancakes",
    "ingredients": ["Flour", "Almond milk", "Eggs"],
    "preparationSteps": "Mix and fry differently."
  }
  

---

Delete a Recipe

DELETE /api/recipe/{id}

Deletes the recipe with the given ID.

• Path Parameters

  Name	Type	Required	Description
  id	Long	Yes	The ID of the recipe to delete.

• Responses

  Status Code	Description
  200 OK	The recipe was successfully deleted. Returns true.
  400 Bad Request	No recipe exists with the given ID.

• Example Request

  curl -X DELETE "https://your-domain.com/api/recipe/123"
  

• Example Response (200)

  true