From fff5f2fffa575c97a4b3380dc13bc34d0d47e514 Mon Sep 17 00:00:00 2001 From: Steven Liu Date: Sat, 22 Nov 2025 12:19:00 +0100 Subject: [PATCH] docs: api definition --- docs/recipe-api.md | 243 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 243 insertions(+) create mode 100644 docs/recipe-api.md diff --git a/docs/recipe-api.md b/docs/recipe-api.md new file mode 100644 index 0000000..e2b9b4f --- /dev/null +++ b/docs/recipe-api.md @@ -0,0 +1,243 @@ +## 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** + + ```bash + curl -X GET "http://SERVER_ADDRESS/api/recipe/1" \ + -H "Accept: application/json" + ``` + +* **Example Response (200)** + + ```json + { + "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)** + + ```bash + curl -X GET "http://SERVER_ADDRESS/api/recipes" \ + -H "Accept: application/json" + ``` + +* **Example Request (with limit)** + + ```bash + curl -X GET "http://SERVER_ADDRESS/api/recipes?limit=10" \ + -H "Accept: application/json" + ``` + +* **Example Response (200)** + + ```json + [ + { + "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: + + ```json + { + "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** + + ```bash + 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)** + + ```json + { + "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: + + ```json + { + "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** + + ```bash + 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)** + + ```json + { + "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** + + ```bash + curl -X DELETE "https://your-domain.com/api/recipe/123" + ``` + +* **Example Response (200)** + + ```json + true + ``` \ No newline at end of file