From e8849f28cca9017264721fc0c2b67d568141b7bd Mon Sep 17 00:00:00 2001
From: Alex Garel <alex@openfoodfacts.org>
Date: Wed, 2 Oct 2024 09:57:27 +0200
Subject: [PATCH] docs: image url in how-to-download-images (#10836)

---
 docs/api/how-to-download-images.md       | 15 +++++++++
 docs/api/ref/schemas/product_images.yaml | 42 ++++++++++++++----------
 2 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/docs/api/how-to-download-images.md b/docs/api/how-to-download-images.md
index 2de6e7d08c231..001f4e8e85d99 100644
--- a/docs/api/how-to-download-images.md
+++ b/docs/api/how-to-download-images.md
@@ -12,6 +12,8 @@ If you plan to download more images, you should instead
 [use the Open Food Facts images dataset hosted on
 AWS](./how-to-download-images.md#download-from-aws).
 
+**NOTE:** please avoid fetching full image if it is not needed, but use image in the right size.
+
 ## Download from AWS
 
 If you want to download many images, this is the recommended
@@ -26,6 +28,18 @@ All images are hosted under the
 [https://images.openfoodfacts.org/images/products/](https://images.openfoodfacts.org/images/products/) folder. 
 But you have to build the right URL from the product info.
 
+## images URL directly available in product data
+
+When you request the API, you will get the url of some important images: front, ingredients, nutrition, packaging
+
+The field [`selected_images`](https://openfoodfacts.github.io/openfoodfacts-server/api/ref-v2/#cmp--schemas-product-images) provides you with those images.
+
+The structure should be simple enough to read. You get different image type, and inside different image size, and inside the urls for the different languages.
+
+## Computing images URL
+
+In get you want to get an image which url is not directly present in product data, you need to compute the image url by yourself.
+
 ### Computing single product image folder
 
 Images of a product are stored in a single directory. The path of this
@@ -147,6 +161,7 @@ In the structure, selected images have additional fields:
 
 For selected images, the filename is the image key followed by the revision number and the resolution: `<image_name>.<rev>.<resolution>.jpg`.
 Resolution must always be specified, but you can use `full` keyword to get the full resolution image.
+`image_name` is the image type + language code (eg: `front_fr`).
 
 In our above example, the filename for the front image in french (`front_fr` key) is:
 * `front_fr.4.400.jpg` for 400 px version
diff --git a/docs/api/ref/schemas/product_images.yaml b/docs/api/ref/schemas/product_images.yaml
index 17ee25c857022..22d8ef556ad0f 100644
--- a/docs/api/ref/schemas/product_images.yaml
+++ b/docs/api/ref/schemas/product_images.yaml
@@ -10,24 +10,6 @@ description: |
   * [Getting images](https://openfoodfacts.github.io/openfoodfacts-server/api/how-to-download-images/)
   * [Uploading images](https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-uploading-photo-to-a-product/)
 properties:
-  image_front_small_url:
-    type: string
-  image_front_thumb_url:
-    type: string
-  image_front_url:
-    type: string
-  image_nutrition_small_url:
-    type: string
-  image_nutrition_thumb_url:
-    type: string
-  image_nutrition_url:
-    type: string
-  image_small_url:
-    type: string
-  image_thumb_url:
-    type: string
-  image_url:
-    type: string
   images:
     description: |
       This contains properties for all images contained on the product.
@@ -60,10 +42,15 @@ properties:
     items:
       type: string
   last_image_t:
+    description: timestamp of last image upload (or update?)
     type: integer
 
   selected_images:
     type: object
+    description: |
+      URL for selected (important) images of the product.
+
+      This is very handy if you display the product to users.
     properties:
       front:
         type: object
@@ -90,3 +77,22 @@ properties:
           See property `front` to get the real type of those objects
           (Put this way because of a [bug in rapidoc](https://github.com/rapi-doc/RapiDoc/issues/880))
         type: string
+
+  image_small_url:
+    type: string
+  image_thumb_url:
+    type: string
+  image_url:
+    type: string
+
+  patternProperties:
+    'image(_(?<image_type>front|packaging|ingredients|nutrition|other))?(_(?<image_size>small|thumb))?_url':
+      description: |
+        the URL of image of type `image_type` in size `image_size` (or full size if not given).
+
+        The `image_type` tells which image the url correspond to. `image_type` is `front` if not provided.
+
+        The image is the one for current language (affected by `lc` parameter) if an image exists for this language, the image in main product language otherwise.
+
+        **IMPORTANT:** you should use `selected_images` field instead of this one.
+      type: string