Skip to main content

Migrating from the V2 API

This page is for integrations built on the earlier Nutritionist Pro web service, described in the document "NexGen RESTful API V1". The customer API returns the same information with a cleaner format, and adds recipes, ingredients, and labels as endpoints of their own.

An integration has to change in four places: the base URL, authentication, the routes, and the field names.

Base URL and authentication​

The customer API has a new base URL:

https://dev.nutritionistpro.com/v3/customer

Authentication uses one key in place of the earlier key and secret pair.

  • Earlier: the secret in the Authorization header, and the key in an api_token query parameter.
  • Now: one API key in the Authorization header, as Authorization: Bearer npcust_....

Earlier keys and secrets are not accepted. Create a new key on the Settings page. See Get started.

Routes​

Recipe books were called books, and their recipes were called foods.

  • GET /books is now GET /recipe-books.
  • GET /books/{book} is now GET /recipe-books/{id}.
  • GET /books/{book}/foods is now GET /recipe-books/{id}/recipes. Add view=full to get the full detail of each recipe, as the earlier route returned.
  • GET /books/date/{date} is now GET /recipe-books?updated_since={date}.
  • GET /books/date/{date_from}/{date_to} is now GET /recipe-books?updated_since={date_from}&updated_until={date_to}.

The earlier date routes returned each changed book together with its recipes. The customer API returns the changed books, and the recipes of each book come from GET /recipe-books/{id}/recipes.

These endpoints are new:

  • GET /recipes and GET /recipes/{id}. Recipes without going through a book.
  • GET /ingredients/{id}. The ingredients behind a recipe.
  • GET /labels and GET /labels/{id}. Labels.

Response format​

Responses are wrapped​

Earlier responses were the record or list itself. Every customer API response is wrapped, with the content in data:

{
  "status": true,
  "code": 200,
  "data": {}
}

Lists are paged​

The earlier routes returned every record in one response. The customer API returns pages of up to 200 records with a meta block. See Lists and syncing.

Errors use HTTP status codes​

Earlier errors were returned with HTTP status 200 and the error code inside the body, with "status": "error". The customer API returns the real HTTP status code, and status is false. See Errors and limits.

A request for a book that does not exist now returns 404. A date that cannot be read returns 400.

Recipe book fields​

  • book_system_id is now id.
  • book_name is now name.
  • foods_count is now recipe_count. A recipe listed twice in a book is counted once.
  • client_id and client_name are now account.id and account.name.
  • creator_id and creator_name are now creator.id and creator.name.
  • foods is now recipes.
  • deleted_foods, a list of objects with a food_system_id, is now deleted_recipe_ids, a list of IDs.

created_at and updated_at are new.

Recipe fields​

  • food_system_id is now id.
  • food_name is now name.
  • unique_code is now code.
  • client_id and client_name are now account.id and account.name.
  • creator_id and creator_name are now creator.id and creator.name.
  • region, a name, is now an object with id and name.
  • preparation_method and meal_component are unchanged. Each is still a single name.
  • preparation_time is unchanged.
  • cooking_time, text such as 90 min(s), is now cooking_time_minutes, a number such as 90.
  • cooking_temprature, text ending in degrees, is now cooking_temperature, the text as entered in the recipe.
  • Instructions (shown as instructions in the earlier documentation), the steps joined with spaces, is now instructions, the steps in order and separated by line breaks.
  • number_of_servings is unchanged.
  • serving_amount_value is now serving.amount.
  • serving_amount_unit is now serving.unit.
  • serving_amount_gram_weight is now serving.gram_weight.
  • allergens, a list of names, is now a list of objects with id and name.

serving.note, nutrient_basis, ingredients, created_at, and updated_at are new.

Nutrient fields​

  • nutrient_name is now name.
  • nutrient_value is now value.
  • nutrient_unit is now unit.

id and abbreviation are new. Match nutrients by id, which does not change if a nutrient is renamed.

The same nutrients are published as before, and values are still for one serving. See Nutrients.

Earlier responses could return nutrients as an object with gaps in its numbering. It is now always a list.

Other differences​

  • Dates in requests were YYYY-MM-DD only. A date and time is now accepted as well.
  • A date range used to include the first instant of the end date only. updated_until with a date now covers that whole day.
  • Recipes in Draft status are no longer returned.
  • A key returns what its owner can see in Nutritionist Pro. The earlier web service returned the data of every user on the account.
  • The earlier web service needed a separate API product on the account. The customer API needs only an active Nutritionist Pro online subscription.

Checklist​

  1. Create an API key on the Settings page.
  2. Change the base URL.
  3. Send the key as Authorization: Bearer, and remove the api_token parameter.
  4. Rename the routes.
  5. Read records from data, and page through lists with limit and offset.
  6. Rename the fields, and handle the values that changed type.
  7. Check HTTP status codes for errors.