-
Notifications
You must be signed in to change notification settings - Fork 0
Backend API Documentation
Thomas edited this page Nov 18, 2019
·
36 revisions
- Get data for all recipes
- Add a new recipe
- Get data for a single recipe
- Update an existing recipe
- Delete a recipe
All responses use JSON formatting and take the following form:
{
"message": "Description of what happened",
"data": "Mixed type holding the content of the response"
}Note that all further response definitions will only include the value of the data field.
All attributes are required unless otherwise specified.
| Attribute | Description |
|---|---|
| id |
string (hash key) Unique identifier for this recipe. |
| name |
string Name of this recipe. |
| difficulty |
string Indicates how challenging this recipe is: Beginner, Intermediate, Advanced, Expert. |
| author |
string (optional) Name of the recipe author. |
| source |
string (optional) Where this recipe came from. |
| length |
integer (system field) Total number of seconds to complete the recipe from start to finish. Automatically updated by the app when steps are added, modified, or removed. |
| date_added |
string (system field) The timezone-less UTC timestamp (ISO 8601) when this recipe was added to the database. |
| start_time |
string (optional) The timezone-less UTC timestamp (ISO 8601) of the most recent start time for this recipe. Defaults to date_added if not provided. |
| steps |
list (optional) List of Step objects. Defaults to an empty list. |
{
"id": "123456.789",
"name": "First Example Recipe",
"difficulty": "Beginner",
"author": "Unnamed technical writer",
"source": "Grandmother's recipe cards",
"length": 0,
"date_added": "2019-10-17 21:02:00.000000Z",
"start_time": "2019-10-19 10:30:00.000000Z",
"steps": []
}All attributes are required unless otherwise specified.
| Attribute | Description |
|---|---|
| number |
integer Step number, used as the unique identifier for each step within a recipe. These are user-provided and should be sequential. |
| text |
string Brief summary of the step |
| then_wait |
integer Once this step is complete, wait this long (in seconds) before starting the next step |
| note |
string (optional) Additional notes/directions for this step |
{
"number": 1,
"text": "Combine ingredients in a large bowl",
"then_wait": 0,
"note": "Do not over-mix!"
}GET / or GET /api
Returns the API documentation with basic HTML markup.
GET /readme
Returns the README.md file for this project with basic HTML markup.
GET /recipes
Returns a list of all recipes, including their embedded steps. If no recipes exist, the endpoint returns an empty list.
| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful. |
[
{
"id": "1560122081.000008",
"name": "Country Sourdough: Pain de Campagne",
"difficulty": "Advanced",
"author": "Ken Forkish",
"source": "Flour Water Salt Yeast",
"length": 97200,
"date_added": "2019-02-15 17:00:00.000000Z",
"start_time": "2019-06-11 10:55:08.000000Z",
"steps": [
{
"number": 1,
"text": "Revive stored levain",
"then_wait": 72000,
"note": "12 to 24 hours, if necessary."
},
{
"number": 2,
"text": "Feed the levain",
"then_wait": 25200,
"note": "6 to 8 hours."
}
]
},
{
"id": "987654.321",
"name": "Second Bread Example",
"difficulty": "Intermediate",
"author": "Unnamed technical writer",
"source": "Mom",
"length": 0,
"date_added": "2019-10-17 21:02:00.000000Z",
"start_time": "2019-10-19 10:30:00.000000Z",
"steps": []
}
]POST /recipes
Adds a new recipe to the database. Returns the newly-created recipe.
Note:
- Any values provided for
id,date_added, orlengthare ignored - It's recommended to create a step-free recipe first, then add steps later
| Code | Title | Description |
|---|---|---|
| 201 | Created | The resource was successfully created. |
| 422 | Validation Error | A validation error occurred. |
{
"name": "Paratha",
"difficulty": "Beginner",
"source": "https://www.seriouseats.com/recipes/2018/07/paratha-flaky-south-asian-flatbread.html"
}{
"id": "1573953898.030828",
"name": "Paratha",
"difficulty": "Beginner",
"source": "https://www.seriouseats.com/recipes/2018/07/paratha-flaky-south-asian-flatbread.html",
"length": 0,
"date_added": "2019-11-16 17:24:58.030849Z",
"start_time": "2019-11-16 17:24:58.030849Z",
"steps": []
}GET /recipes/<recipe_id>
Returns a single recipe object, including any embedded steps.
| param | Description |
|---|---|
| recipe_id |
string (required) Unique identifier for this recipe. |
| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 404 | Not Found | The specified recipe was not found. |
GET /recipes/123456.789
{
"id": "123456.789",
"name": "First Example Recipe",
"difficulty": "Beginner",
"author": "Unnamed technical writer",
"source": "Grandmother's recipe cards",
"length": 0,
"date_added": "2019-10-17 21:02:00.000000Z",
"start_time": "2019-10-19 10:30:00.000000Z",
"steps": []
}PUT /recipes/<recipe_id>
Modifies data of the specified recipe. Returns the recipe updated.
| param | Description |
|---|---|
| recipe_id |
string (required) Unique identifier for this recipe. |
Updates are permitted for the following recipe attributes:
| Attribute |
|---|
| name |
| difficulty |
| author |
| source |
| start_time |
| steps |
| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 404 | Not Found | The specified recipe was not found. |
| 422 | Validation Error | Validation failure on one (or more) fields. |
{
"id": "1232101001.98765",
"name": "Flaky South Asian Flatbread (Paratha)",
"difficulty": "Intermediate"
}DELETE /recipes/<recipe_id>
Deletes the specified recipe. No value for data is returned by this endpoint.
| param | Description |
|---|---|
| recipe_id |
string (required) Unique identifier for this recipe. |
| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 404 | Not Found | The specified recipe was not found. |
PUT /recipes/<recipe_id>/<step_number>
Adds or updates a step to the specified recipe. The response for this PUT request only returns a status.
| param | Description |
|---|---|
| recipe_id |
string (required) Unique identifier for this recipe. |
| step_number |
integer (required) The step number to add/update. |
| Code | Title | Description |
|---|---|---|
| 201 | Created | The resource was successfully created. |
| 404 | Not Found | The specified recipe was not found. |
| 422 | Validation Error | Validation failure on one (or more) fields. |
{
"recipe_id": "1232101001.98765",
"number": 4,
"text": "Fold the dough",
"then_wait": 900
}GET /recipes/<id>/<step_number>
Returns a step object.
| param | Description |
|---|---|
| recipe_id |
string (required) Unique identifier for this recipe. |
| step_number |
integer (required) The step number to return. |
| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 404 | Not Found | The specified recipe or step was not found. |
GET /recipes/1560122081.000008/2
{
"number": 2,
"text": "Feed the levain",
"then_wait": 25200,
"note": "6 to 8 hours."
}DELETE /recipes/<recipe_id>/<step_number>
Deletes the step number indicated. Returns a list of the remaining steps for that recipe.
| param | Description |
|---|---|
| recipe_id |
string (required) Unique identifier for this recipe. |
| step_number |
integer (required) Number of the step to delete. |
GET /replacements/<scope>
Returns a collection of replacements used for applying Paprika-compliant formatting.
| param | Description |
|---|---|
| scope |
string (required) Defines the scope of replacements to return. |
Scope options:
-
all-- Returns all records. -
directions-- Returns only the replacements for use on directions. -
ingredients-- Returns only the replacements for use on ingredients.
| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 404 | Not Found | The specified scope is invalid. |
| Type | Description |
|---|---|
| params_invalid | Provided parameter(s) were not valid. |
| unknown_record | Record was not found. |
| unknown_route | URL was not valid. |
{
"message": "Validation Error",
"data": "Step number must be an integer."
}| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 201 | Created | The resource was successfully created. |
| 404 | Not Found | The resource does not exist. |
| 422 | Validation Error | A validation error occurred. |
| 500 | Internal Error | An error occurred within the API. |