From 4cb613a5c912e16aedc8114df6bd519cae72e06b Mon Sep 17 00:00:00 2001
From: rr-
Date: Sat, 7 Jan 2017 10:44:01 +0100
Subject: server/posts: change reverse image search API

Add exact duplicates search; refactor to use classes over dictionaries
---
 API.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

(limited to 'API.md')

diff --git a/API.md b/API.md
index 2b38172..43c6dd9 100644
--- a/API.md
+++ b/API.md
@@ -1070,17 +1070,15 @@ data.
 
 - **Output**
 
-    A list of [image search results](#image-search-result).
+    An [image search result](#image-search-result).
 
 - **Errors**
 
-    - input file is not an image
     - privileges are too low
 
 - **Description**
 
-    Retrieves posts that look like the input image. Works only on images and
-    animations, i.e. does not work for videos and Flash movies.
+    Retrieves posts that look like the input image.
 
 ## Listing comments
 - **Request**
@@ -2152,14 +2150,15 @@ A result of reverse image search operation.
 
 ```json5
 {
-    "results": [
+    "exactPost": <exact-post>,
+    "similarPosts": [
         {
-            "dist": <distance>,
-            "post": <post>
+            "distance": <distance>,
+            "post": <similar-post>
         },
         {
-            "dist": <distance>,
-            "post": <post>
+            "distance": <distance>,
+            "post": <similar-post>
         },
         ...
     ]
@@ -2167,9 +2166,14 @@ A result of reverse image search operation.
 ```
 
 **Field meaning**
-- `<dist>`: distance from the original image (0..1). The lower this value is, the more similar the
-post is.
-- `<post>`: a [post resource](#post).
+-  `exact-post`: a [post resource](#post) that is exact byte-to-byte duplicate
+   of the input file. May be `null`.
+- `<similar-post>`: a [post resource](#post) that isn't exact duplicate, but
+   visually resembles the input file. Works only on images and animations, i.e.
+   does not work for videos and Flash movies. For non-images and corrupted
+   images, this list is empty.
+- `<distance>`: distance from the original image (0..1). The lower this value
+   is, the more similar the post is.
 
 # Search
 
-- 
cgit v1.3