From 2fad6b0b60b0d5e861d572acf29947086be3cd20 Mon Sep 17 00:00:00 2001 From: Ben Kurtovic Date: Sat, 13 Sep 2014 20:38:08 -0500 Subject: [PATCH] Description of API response data. --- copyvios/api.py | 17 +++++++++++-- templates/api.mako | 72 +++++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 81 insertions(+), 8 deletions(-) diff --git a/copyvios/api.py b/copyvios/api.py index 93f9964..4826245 100644 --- a/copyvios/api.py +++ b/copyvios/api.py @@ -51,8 +51,21 @@ def format_api_error(code, info): def handle_api_request(): query = Query() - action = query.action.lower() if query.action else "" - return _HOOKS.get(action, _hook_default)(query) + if query.version: + try: + query.version = int(query.version) + except ValueError: + info = "The version string is invalid: {0}".format(query.version) + return format_api_error("invalid_version", info) + else: + query.version = 1 + + if query.version == 1: + action = query.action.lower() if query.action else "" + return _HOOKS.get(action, _hook_default)(query) + + info = "The API version is unsupported: {0}".format(query.version) + return format_api_error("unsupported_version", info) def _hook_default(query): info = u"Unknown action: '{0}'".format(query.action.lower()) diff --git a/templates/api.mako b/templates/api.mako index e4a4140..3bacf69 100644 --- a/templates/api.mako +++ b/templates/api.mako @@ -59,13 +59,13 @@ project string Yes - The project name of the site the page lives on. Examples are wikipedia and wiktionary. A list of acceptable values can be retrieved using action=sites. + The project code of the site the page lives on. Examples are wikipedia and wiktionary. A list of acceptable values can be retrieved using action=sites. lang string Yes - The language name of the site the page lives on. Examples are en and de. A list of acceptable values can be retrieved using action=sites. + The language code of the site the page lives on. Examples are en and de. A list of acceptable values can be retrieved using action=sites. title @@ -100,13 +100,13 @@ project string Yes - The project name of the site the page lives on. Examples are wikipedia and wiktionary. A list of acceptable values can be retrieved using action=sites. + The project code of the site the page lives on. Examples are wikipedia and wiktionary. A list of acceptable values can be retrieved using action=sites. lang string Yes - The language name of the site the page lives on. Examples are en and de. A list of acceptable values can be retrieved using action=sites. + The language code of the site the page lives on. Examples are en and de. A list of acceptable values can be retrieved using action=sites. title @@ -152,9 +152,69 @@

Responses

-

+

The JSON response object always contains a status key, whose value is either ok or error. If an error has occurred, the response will look like this:

+
{
+    "status": "error",
+    "error": {
+        "code": (string) error code,
+        "info": (string) human-readable description of error
+    }
+}
+

Valid responses for action=compare and action=search are formatted like this:

+
{
+    "status": "ok",
+    "meta": {
+        "time":       (float) time to generate results, in seconds,
+        "queries":    (int) number of search engine queries made,
+        "cached":     (boolean) whether or not these results are cached from an earlier search (always false in the case of action=compare),
+        (only if cached=true) "cache_time": (float) time to generate the original, uncached results, in seconds
+        "redirected": (boolean) whether or not a redirect was followed
+    },
+    "page": {
+        "title": (string) the normalized title of the page checked,
+        "url":   (string) the full URL of the page checked
+    },
+    (only if redirected=true) "original_page": {
+        "title": (string) the normalized title of the original page whose redirect was followed,
+        "url":   (string) the full URL of the original page whose redirect was followed
+    },
+    "best": {
+        "url":        (string) the URL of the best match found, or null if no matches were found,
+        "confidence": (float) the confidence of a violation in the best match, or 0.0 if no matches were found,
+        "violation":  (string) one of "suspected", "possible", or "none"
+    },
+    "sources": [
+        {
+            "url":        (string) the URL of the source,
+            "confidence": (float) the confidence of a violation in the source,
+            "violation":  (string) one of "suspected", "possible", or "none",
+            "skipped":    (boolean) whether or not the source was skipped due to the check finishing early (see note about noskip above)
+        },
+        ...
+    ]
+}
+

In the case of action=search, sources will contain one entry for each source checked (or skipped if the check ends early), sorted in order of confidence, with skipped sources at the bottom.

+

In the case of action=compare, best will always contain information about the URL that was given, so response["best"]["url"] will never be null. Also, sources will always contain one entry, with the same data as best, since only one source is checked in comparison mode.

+

Valid responses for action=sites are formatted like this:

+
{
+    "status": "ok",
+    "langs": [
+        [
+            (string) language code,
+            (string) human-readable language name
+        ],
+        ...
+    ],
+    "projects": [
+        [
+            (string) project code,
+            (string) human-readable project name
+        ],
+        ...
+    ]
+}

Example

-

+

GET https://tools.wmflabs.org/copyvios/api.json?version=1&action=search&project=wikipedia&lang=en&title=User:The_Earwig/Sandbox/CopyvioExample

% endif % if result: