logo
Powered by Redocly

Recipe API (v1)

Download OpenAPI specification:Download

E-mail: support@smartwithfood.com URL: https://smartwithfood.atlassian.net/servicedesk/customer/portal/6 License: Proprietary License

Introduction

Welcome to the Developer Portal for the SmartWithFood Recipe API. The highlight of this API is the productize endpoint. This powerful feature enables you to convert individual recipes into comprehensive shopping lists with a single API call. Seamlessly integrate this functionality into your application, making it easier than ever for users to gather ingredients for their next culinary adventure.

On this developer portal you find the API specifications including a short description of every field, a request example and a response example for every endpoint, and security information, as well as information about the non-functional requirements you can expect from our API is provided. Furthermore, you can find information on how to get started using our API and on who to contact when you are in need of further assistance.

Getting started

Follow the following steps to easily get started with our Recipe API.

  1. Express your interest in using our API: Contact us via support@smartwithfood.com and we will provide you with all of the information you need to get started with our API.
  2. Explore Documentation: Dive into our detailed API documentation, where you will find information on endpoints, request parameters, response formats, and usage examples.
  3. Integrate and Innovate: Use the API to access recipes and leverage the productize endpoint to enhance your application's shopping list capabilities

Support

Should you have any questions or need further assistance, please do not hesitate to contact our support team at support@smartwithfood.com or at https://smartwithfood.atlassian.net/servicedesk/customer/portal/6.

Change Log

The change log in our API developer portal serves as a chronological record detailing updates, enhancements, and modifications to the API, offering developers a transparent history of changes and version releases for improved clarity and understanding.

Version 1.0.1 - Released to STA on 2024-04-02, Released to PRD on 2024-05-28

Modified 'article' object

  • Added 'names', 'brands', 'isPrivateLabel', 'labels', 'weightConversionFactor', 'orderUnits' attributes.
  • Impacted endpoints:
    • POST /productize

Modified 'article' promotions object

  • Added 'identifiers' attribute.
  • Impacted endpoints:
    • POST /productize

Non-Functional Requirements

We are committed to providing you with a seamless and reliable experience when integrating our API into your applications. Below you can find the non-functional requirements you can expect from our API.

Performance

Productize

  • 99% of requests are expected to have a response time of less than 10 seconds.
  • 95% of requests are expected to have a response time of less than 3 seconds.

Availability

Our API aims for an availability of 99.9%. This translates to approximately 8.5 hours of planned downtime per year.

Throughput

Normal Circumstances

  • Up to 2 requests per second.
  • Up to 40 concurrent requests per minute.
  • Up to 60,000 requests per day.

Peak Circumstances

  • Up to 30 requests per second.
  • Up to 700 concurrent requests per minute.
  • Up to 33,500 requests per hour.
  • Up to 140,000 requests per day.

API Reference

With this Recipe API you can:

  • convert a recipe ID, a recipe identifier or a list of recipe ingredients to articles by using the POST /productize.

Productize

Convert a recipe ID, a recipe identifier or a list of recipe ingredients to articles.

SecurityoAuth2-clientCredentials
Request
header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1) - When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Request Body schema: application/json
articleLimit
number <= 10
Default: 1

The amount of items returned per page.

lines
Array of strings

List of recipe ingredients that will be converted to articles.

recipe
string

Recipe Id (UUID) or recipe identifier (type:identifier) of the recipe that will be converted to articles.

select
Array of strings

If no select parameter is sent in the request, a default object will be returned. If a select parameter is sent in the request, the fields specified in the select will be returned.

Following fields are part of the default object: recipe.id, recipe.title, recipe.cookTime, recipe.prepTime, recipe.totalTime, recipe.yield, recipe.portionWeight, recipe.nutriScore, recipe.budget, recipe.difficulty, recipe.media, article.id, article.name, article.brand, article.media, article.ecoScore, article.nutriScore, article.servings, article.amount, article.amountUnit, article.isWeightArticle, article.isPrivateLabel, article.weightConversionFactor, article.orderUnits.

Following fields will only be returned if specified in the select parameter: recipe.identifiers, recipe.description, recipe.allergens, recipe.lifestyles, recipe.preferences, recipe.lines, recipe.warehouses, recipe.tips, recipe.tags, recipe.utensils, recipe.nutritionalsPer100gram, recipe.nutritionalsPerPortion, recipe.price, recipe.externalUrl, recipe.status, recipe.customFields, recipe.createdAt, recipe.modifiedAt, recipe.instructions, article.relevance, article.description, article.identifiers, article.barcodes, article.warehouses, article.allergens, article.lifestyles, article.preferences, article.promotions, article.customFields, article.labels, article.names, article.brands.

warehouses
required
Array of strings

List of specific warehouses to search in. The list can contain UUIDs or warehouse identifiers defined by the tenant. Identifiers should be specified as 'identifierType:identifier'. We advise our customers to use identifiers (and not UUIDs) to filter on warehouses.

brands
Array of strings

List of specific brands to search in.

object

Allergens the returned articles should (not) contain.

object

Lifestyles the returned articles should (not) contain.

object

Preferences the returned articles should (not) contain.

mediaSizes
Array of strings

List of the types of media that will be returned.

customerId
string

The customerId of the customer that is invoking the service. This is used to look up the Most Frequently Bought information. When a customerId is passed, but no relevant record is found in the Customer resource, the system will silently ignore the customerId.

sort
Array of strings

The productize supports the following three values for sorting:

  • price of a specified priceType asc/desc, specified as 'price:priceType:asc' or 'price:priceType:desc'
  • measurementUnitPrice of a specified priceType asc/desc, specified as 'measurementUnitPrice:priceType:asc' or 'measurementUnitPrice:priceType:desc'
  • nutri-score, specified as 'nutriscore:asc' or 'nutriscore:desc'
  • eco-score, specified as 'ecoscore:asc' or 'ecoscore:desc'

A combination can be used to search, however every supported sort variable can only be used once. When no sort parameter is entered, the search will default to relevance.

customFields
Array of strings

List of customFields to search in. The customField value should be specified as 'customFieldUUID:customFieldValue' or as 'customFieldName:customFieldValue'.

baseYield
number
Default: 4

Sets the recipe yield if no recipeId is specified.

The lines of the response will be adapted to the specified yield (amount of portions).

targetYield
number

Overrides the yield specified in the recipe or in baseYield.

The lines will be adapted to the specified yield (amount of portions).

object

Narrows down the returned articles based on the relevance of the article. There are 8 levels of relevance:

  • the level 'override' contains articles that have been manually specified and is only used by the productize service;
  • the level 'exactMatch' contains articles that match the food concept and attribute values of the input;
  • the level 'closeVariant' contains articles that match the food concept of the input, but not all other attribute values, and is based on business rules defined by the SWF dieticians;
  • the level 'distantVariant' contains articles that match the food concept of the input, but not all other attribute values;
  • the level 'closeSubstitute' contains articles that match the attribute values of the input, but not the food concept, and is based on business rules defined by the SWF dieticians;
  • the level 'distantSubstitute' contains articles that match the attribute values of the input, but not the food concept;
  • the level 'derivatives' contains articles that are derived from the input, based on business rules specified by SWF in accordance with the retailer;
  • the level 'textSearch' contains articles of which the name matches exactly with the word(s) typed into the search bar.
Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

post/productize
Request samples
application/json
{
  • "articleLimit": 1,
  • "lines": [
    ],
  • "recipe": "666f17f0-382e-431b-9275-2e3bbb482771",
  • "select": [
    ],
  • "warehouses": [
    ],
  • "brands": [
    ],
  • "allergens": {
    },
  • "lifestyles": {
    },
  • "preferences": {
    },
  • "mediaSizes": [
    ],
  • "customerId": "1234585",
  • "sort": [
    ],
  • "customFields": [
    ],
  • "baseYield": 4,
  • "targetYield": 6,
  • "relevance": {
    }
}
Response samples
application/json
{
  • "totalLines": 12,
  • "recipe": {
    },
  • "lines": [
    ],
  • "yield": 6
}