243 lines
No EOL
6.1 KiB
Markdown
243 lines
No EOL
6.1 KiB
Markdown
## 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
|
|
``` |