NAV

Introduction

API Endpoint

https://recipes.lancaster.ac.uk/api/v1/

Welcome to the Lancaster University Recipes API. You can use our API to access recipes from the Lancaster University Recipes platform developed by the Innovation Hub.

The Recipes API is organised around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application. JSON will be returned in all responses from the API, including errors.

Using the Recipes API, you can retrieve recipes and their corresponding data.

You can view example requests in the dark area to the right.

Icon design by Yorlmar Campos

Errors

Error example

    {
        "error": {
            "type":"bad_parameter",
            "message":"Bad Parameter(s): parameter_name",
            "status":400
        }
    }

The Recipes API uses conventional HTTP response codes to indicate success or failure of an API request. It also returns a JSON object with more detailed explanations of the issue. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with our servers.


Status Codes

Code Meaning
200
OK
Everything worked as expected.
400
Bad Request
Invalid Request
404
Not Found
The specified could not be found
500
Internal Server Error
We had a problem with our server. Try again later.
503
Service Unavailable
We’re temporarily offline for maintenance. Please try again later.


Error Types

Error Meaning
bad_parameter
One of the sent parameters is not allowed or not recognised by the API
integer_expected
One of the params contains invalid characters or is a string when integer is expected
bad_id
Specified id could not be found
bad_field
One of fields is not recognized by the API
bad_order_field
Order field provided is not valid

Recipes

The recipes object

Attributes Information
id
Integer
Unique ID of a recipe
title
String
Title of a recipe
description
String
Description of a recipe
author
String
Author of a recipe
serves
String
Amount of serves
calories
Integer
Amount of calories
image
String
Link to a recipe’s image
steps
Array of Strings
Cooking steps
ingredients
Array of Objects
List of ingredients with the required amount
cuisine
String
Name of a cuisine
created_at
Timestamp
Recipe creation time
updated_at
Timestamp
Last update time

Retrieve a specific recipe

You can retrieve a specific recipe by specifying its id.

Definition

GET https://recipes.lancaster.ac.uk/api/v1/recipes/{RECIPE_ID}

Example Request

curl https://recipes.lancaster.ac.uk/api/v1/recipes/1

Example response

Retrieve all recipes

You can retrieve a complete list of all available recipes via the API.

Definition

GET https://recipes.lancaster.ac.uk/api/v1/recipes

Example Request

curl https://recipes.lancaster.ac.uk/api/v1/recipes

Example response

    {
        "recipes": [
            {
                "id": 1,
                "title": "Mashed Potatoes",
                "description": "Delicious mashed potatoes",
                "author": "PotatoMan",
                "serves": "3",
                "calories": 150,
                "image": "recipes.lancaster.ac.uk/images/chef.png",
                "steps": ["Boil potatoes", "Mash potatoes"],
                "ingredients": [
                    {
                        "Potatoes": "5",
                        "Salt": "a pinch of salt"
                    }
                ],
                "cuisine": "Australian"
            }
        ]
    }

Recipe Filters

Definition

GET https://recipes.lancaster.ac.uk/api/v1/recipes?{FILTER=Value&FILTER=Value}
or
GET https://recipes.lancaster.ac.uk/api/v1/recipes/{RECIPE_ID}?{FILTER=Value&FILTER=Value}

Curl Definition

curl https://recipes.lancaster.ac.uk/api/v1/recipes?{FILTER&FILTER}
      or
curl https://recipes.lancaster.ac.uk/api/v1/recipes/{RECIPE_ID}?{FILTER&FILTER}

Filters allow to specify exactly what data and fields need to be returned and their format. Plural filters can accept multiple parameters separated with ’,’

Examples (API Endpoint: https://recipes.lancaster.ac.uk/api/v1/)

GET recipes?ids=1,2,5 => records with ids 1,2,5
GET recipes?fields=title,author => only specified fields in response
GET recipes?order=author_desc => order by author; descending order
GET recipes?limit=2 => returns only two records
GET recipes?titles=apple,banana => records with titles "apple" and "banana"
GET recipes?titles_like=app => apple, pineapple...
GET recipes?description_contains=bananas => tasty bananas...
GET recipes?authors=steve => recipes created by Steve
GET recipes?authors_like=ste => recipes created by Steve, Stefan...
GET recipes?calories=200 => recipes with 200 calories
GET recipes?calories_leq=250 => calories less or equal to 250
GET recipes?calories_geq=100 => calories more or equal to 100
GET recipes?cuisine_ids=13 => recipes with cuisine ID = 13
GET recipes?cuisines=australian => Australian cuisine
Filters Information
ids
Returns only recipes with specified IDs
fields
Returns only specified fields. Permitted values: id, title, description, author, serves, calories, image, cuisine, steps, ingredients
order
Returns recipes in a specified order. Accepts {FIELD_NAME} and optional “_desc” suffix if data needs to be sorted in descending order, otherwise it will be sorted in ascending order
limit
Returns only specified amount of records
titles
Returns recipes with specified titles
titles_like
Returns recipes that have specified titles as substrings of full titles
description_contains
Returns recipes that contain any of the specified keywords in the description
authors
Returns recipes that were created by specified authors
authors_like
Returns recipes that have specified strings as substrings of author names
calories
Returns recipes with specified amount of calories
calories_leq
Returns recipes with amount of calories less or equal to specified value
calories_geq
Returns recipes with amount of calories greater or equal to specified value
cuisine_ids
Returns recipes with specified cuisine_ids
cuisines
Returns recipes with specified cuisine names

Cuisines

The cuisine object

Attributes Information
id
Integer
Unique ID of a cuisine
name
String
Name of a cuisine

Retrieve a specific cuisine

You can retrieve a specific cuisine by specifying its id.

Definition

GET https://recipes.lancaster.ac.uk/api/v1/cuisines/{CUISINE_ID}

Example Request

curl https://recipes.lancaster.ac.uk/api/v1/cuisines/{CUISINE_ID}

Retrieve all cuisines

You can retrieve a complete list of all available cuisines via the API.

Definition

GET https://recipes.lancaster.ac.uk/api/v1/cuisines

Example Request

curl https://recipes.lancaster.ac.uk/api/v1/cuisines

Example response

    {
        "cuisines": [
            {
            "id": 1,
            "name": "American"
            }
        ]
    }

Cuisine Filters

Definition

GET https://recipes.lancaster.ac.uk/api/v1/cuisines?{FILTER=Value&FILTER=Value}
or
GET https://recipes.lancaster.ac.uk/api/v1/cuisines/{CUISINE_ID}?{FILTER=Value&FILTER=Value}

Curl Definition

curl https://recipes.lancaster.ac.uk/api/v1/cuisines?{FILTER&FILTER}
      or
curl https://recipes.lancaster.ac.uk/api/v1/cuisines/{CUISINE_ID}?{FILTER&FILTER}

Examples (API Endpoint: https://recipes.lancaster.ac.uk/api/v1/)

Filters allow to specify exactly what data and fields need to be returned and their format. Plural filters can accept multiple parameters separated with ’,’

curl cuisines?ids=1,2,5 => records with ids 1,2,5
curl cuisines?order=name_desc => order by name; descending order
GET recipes?limit=2 => returns only two records
curl cuisines?names=american => American cuisine
curl cuisines?names_like=ame => American, Vietnamese...
Filters Information
ids
Returns only cuisines with specified IDs
order
Returns cuisines in a specified order. Accepts {FIELD_NAME} and optional “_desc” suffix if data needs to be sorted in descending order, otherwise it will be sorted in ascending order
limit
Returns only specified amount of records
names
Returns cuisines with specified names
names_like
Returns cuisines that have specified strings as substring of full names