docs: document stream versioning endpoints

source/endpoints/streams.rst

@@ -9,6 +9,8 @@ Main responsabilities of this endpoint are:
 * get a collection of streams, using usual :ref:`get-filters`
 * link a :term:`stream` to a media object
 * remove an existing stream
+* upload a new version of an existing stream
+* replace the latest version of an existing stream in place
 
 Upload file and create stream
 -----------------------------
@@ -271,6 +273,114 @@ Link a stream to a media using ``PATCH /streams/{stream_uuid}/relationships/obje
         }
     }
 
+Upload a new version of a stream
+--------------------------------
+
+``POST /streams/version/{object_id}/{file_name}`` uploads a new version of a file for an existing media object.
+The version counter is incremented automatically (``MAX + 1``). The first version for an object is ``1``.
+
+.. http:post:: /streams/version/(object_id)/(file_name)
+
+    Upload a new version of a file, passing it as binary in `body`.
+    Returns ``409 Conflict`` if the incoming file (SHA-1 hash) is identical to the latest existing version.
+
+    :query private_url: (optional) ``true`` or ``false`` — whether the uploaded stream should use a private URL.
+
+**Example request**:
+
+.. sourcecode:: http
+
+    POST /streams/version/42/myfile-v2.png HTTP/1.1
+    Host: example.com
+    Accept: application/vnd.api+json
+    Content-Type: image/png
+    Authorization: Bearer <jwt>
+
+**Example response**:
+
+.. sourcecode:: http
+
+    HTTP/1.1 201 Created
+    Content-Type: application/vnd.api+json
+    Location: http://example.com/streams/7a1b2c3d-4e5f-6789-abcd-ef0123456789
+
+    {
+        "data": {
+            "id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
+            "type": "streams",
+            "attributes": {
+                "file_name": "myfile-v2.png",
+                "mime_type": "image/png",
+                "version": 2
+            },
+            "meta": {
+                "..." : "..."
+            },
+            "relationships": {
+                "object": {
+                    "links": {
+                        "related": "http://example.com/streams/7a1b2c3d-4e5f-6789-abcd-ef0123456789/object",
+                        "self": "http://example.com/streams/7a1b2c3d-4e5f-6789-abcd-ef0123456789/relationships/object"
+                    }
+                }
+            }
+        }
+    }
+
+Replace the latest version of a stream
+---------------------------------------
+
+``PATCH /streams/version/{object_id}/{file_name}`` replaces the latest version of a stream in place.
+No new version number is created — the existing latest version record is overwritten.
+
+.. http:patch:: /streams/version/(object_id)/(file_name)
+
+    Replace the latest version of a stream, passing the new file as binary in `body`.
+    Returns ``409 Conflict`` if the file content (SHA-1 hash) is identical to the existing latest version.
+    Returns ``404 Not Found`` if no streams exist for the given object.
+
+    :query private_url: (optional) ``true`` or ``false`` — whether the stream should use a private URL.
+
+**Example request**:
+
+.. sourcecode:: http
+
+    PATCH /streams/version/42/myfile-v2.png HTTP/1.1
+    Host: example.com
+    Accept: application/vnd.api+json
+    Content-Type: image/png
+    Authorization: Bearer <jwt>
+
+**Example response**:
+
+.. sourcecode:: http
+
+    HTTP/1.1 200 OK
+    Content-Type: application/vnd.api+json
+
+    {
+        "data": {
+            "id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
+            "type": "streams",
+            "attributes": {
+                "file_name": "myfile-v2.png",
+                "mime_type": "image/png",
+                "version": 2
+            },
+            "meta": {
+                "..." : "..."
+            },
+            "relationships": {
+                "object": {
+                    "links": {
+                        "related": "http://example.com/streams/7a1b2c3d-4e5f-6789-abcd-ef0123456789/object",
+                        "self": "http://example.com/streams/7a1b2c3d-4e5f-6789-abcd-ef0123456789/relationships/object"
+                    }
+                }
+            }
+        }
+    }
+
 Get an image
 ------------