Update API reference to mention x-openstack-image-size header

Add API reference documentation for the x-openstack-image-size header
in PUT /v2/images/{image_id}/file and PUT /v2/images/{image_id}/stage
endpoints.

Assisted-By: Cursor (claude-3.5-sonnet)
Change-Id: Ie733373c093bed4866719f163a75abaff4abe6a2
Signed-off-by: Abhishek Kekane <akekane@redhat.com>

api-ref/source/v2/images-data.inc

@@ -31,6 +31,12 @@ header.  If the store identifier specified is not recognized, a 400 (Bad
 Request) response is returned.  When the header is not present, the image
 data is placed into the default backing store.
 
+An optional ``x-openstack-image-size`` header may be added to the request.
+When present, the server will validate that the uploaded data size matches
+this value. If the actual size does not match the expected size, a 400
+(Bad Request) response is returned. When not present, the server will
+calculate the image size based on the actual request body size.
+
 * Store identifiers are site-specific.  Use the :ref:`Store
   Discovery <store-discovery-call>` call to determine what
   stores are available in a particular cloud.
@@ -49,6 +55,7 @@ Example call:
    curl -i -X PUT -H "X-Auth-Token: $token" \
       -H "X-Image-Meta-Store: {store_identifier}" \
       -H "Content-Type: application/octet-stream" \
+      -H "x-openstack-image-size: 5368709120" \
       -d @/home/glance/ubuntu-12.10.qcow2 \
       $image_url/v2/images/{image_id}/file
 
@@ -98,6 +105,7 @@ Request
 
    - Content-type: Content-Type-data
    - X-Image-Meta-Store: store-header
+   - x-openstack-image-size: x-openstack-image-size
    - image_id: image_id-in-path
 
 

api-ref/source/v2/images-import.inc

@@ -118,12 +118,19 @@ the :ref:`Image Import <image-import-call>` call is made.
 
 Set the ``Content-Type`` request header to ``application/octet-stream``.
 
+An optional ``x-openstack-image-size`` header may be added to the request.
+When present, the server will validate that the uploaded data size matches
+this value. If the actual size does not match the expected size, a 400
+(Bad Request) response is returned. When not present, the server will
+calculate the image size based on the actual request body size.
+
 Example call:
 
 ::
 
    curl -i -X PUT -H "X-Auth-Token: $token" \
       -H "Content-Type: application/octet-stream" \
+      -H "x-openstack-image-size: 5368709120" \
       -d @/home/glance/my.to-import.qcow2 \
       $image_url/v2/images/{image_id}/stage
 
@@ -170,6 +177,7 @@ Request
 .. rest_parameters:: images-parameters.yaml
 
    - Content-type: Content-Type-data
+   - x-openstack-image-size: x-openstack-image-size
    - image_id: image_id-in-path
 
 

api-ref/source/v2/images-parameters.yaml

@@ -97,6 +97,16 @@ stores-header:
   in: header
   required: false
   type: string
+x-openstack-image-size:
+  description: |
+    The expected size of the image data in bytes. When present, the server
+    will validate that the uploaded data size matches this value. If the
+    actual size does not match the expected size, a 400 (Bad Request)
+    response is returned. When not present, the server will calculate the
+    image size based on the actual request body size.
+  in: header
+  required: false
+  type: string
 
 # variables in path
 image_id-in-path:

releasenotes/notes/add-x-openstack-image-size-header-9199a5544274002a.yaml

@@ -0,0 +1,17 @@
+---
+features:
+  - |
+    Added support for the optional ``x-openstack-image-size`` header in image
+    upload endpoints. This header allows clients to specify the expected size
+    of image data in bytes when uploading images via the PUT
+    ``/v2/images/{image_id}/file`` and PUT ``/v2/images/{image_id}/stage``
+    endpoints.
+
+    When the header is present, the server validates that the uploaded data
+    size matches the specified value. If the actual size does not match the
+    expected size, a 400 (Bad Request) response is returned. When the header
+    is not present, the server calculates the image size based on the actual
+    request body size.
+
+    This feature improves data integrity validation during image uploads and
+    helps prevent incomplete or corrupted uploads.