Воспроизводимое чтение через публичный API Tvijo Wiki

Публичный API Tvijo Wiki позволяет читать опубликованные статьи без входа и ключа API. Чтобы позже воспроизвести чтение, сохраните вместе адрес статьи, язык, хеш текста, время наблюдения и лицензию. Одного названия недостаточно: содержание страницы может измениться.

Как найти и прочитать статью

В документации API описан интерфейс только для чтения. Английская статья доступна по /api/wiki/pages/<slug>, русская редакция — по /api/wiki/pages/ru/<slug>. Для просмотра списка используйте /api/wiki/pages?lang=en&limit=20&offset=0 и /api/wiki/sections. Запрос /api/wiki/search?q=<urlencoded>&lang=ru ищет с указанным языком; поисковую фразу нужно закодировать для URL. Результат поиска и фрагмент помогают найти материал, но перед использованием утверждения прочитайте статью целиком. Публичного метода /context в этом контракте нет.

В ответе находятся content_md, url, lang, sha256 и блок лицензии. Хеш вычисляется по байтам возвращённого текста Markdown в UTF-8. Он определяет именно этот текст, а не достоверность, права или весь ответ. Поле updated содержит время публикации и не обязательно показывает время последнего изменения текста.

Проверка сохранённой версии

Передайте имеющийся хеш в ?sha256=<held>. Если текущий текст совпадает, сервер вернёт 200. При расхождении придёт 409 с ошибкой stale_revision и полем current_sha256. Получите новый текст и заново проверьте ответ, основанный на прежнем. Сохраните обозначение старой версии вместо его незаметной подмены.

Кеширование HTTP решает другую задачу. ETag относится к представлению HTTP; заголовок If-None-Match может дать ответ 304, если представление не изменилось. Хеш тела и ETag не взаимозаменяемы.

Упражнение: проверка публичного источника

Запустите пример на Python со стандартной библиотекой. Он читает существующее упражнение об ответах с источниками, проверяет хеш текста и запрашивает заведомо устаревшую версию:

import datetime, hashlib, json, urllib.error, urllib.request
url = 'https://tvijo.com/api/wiki/pages/ru/source-linked-answers-practice'
headers = {'User-Agent': 'TvijoWikiExample/1.0'}
request = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(request, timeout=20) as response:
    page = json.load(response)
assert hashlib.sha256(page['content_md'].encode('utf-8')).hexdigest() == page['sha256']
receipt = {key: page[key] for key in ('url', 'lang', 'sha256', 'license')}
receipt['observed_utc'] = datetime.datetime.now(datetime.timezone.utc).isoformat()
probe = urllib.request.Request(url + '?sha256=' + '0' * 64, headers=headers)
try:
    with urllib.request.urlopen(probe, timeout=20):
        raise AssertionError('Expected a stale-revision response')
except urllib.error.HTTPError as error:
    result = json.load(error)
    assert error.code == 409 and result['error'] == 'stale_revision'
    receipt['stale_revision_status'] = error.code
print(json.dumps(receipt, ensure_ascii=False, indent=2))

Ожидаемый ответ на второй запрос — 409 stale_revision. Сохраните выведенные время наблюдения и лицензию вместе с остальными полями записи проверки. Если запрос не удался или ответ отличается, сохраните результат и разберитесь с причиной, прежде чем считать упражнение выполненным.

Лицензия Wiki разрешает повторное использование при указании источника и ссылке на страницу. Сохраняйте условия вместе с используемым текстом: метаданные стороннего источника сами по себе не дают права копировать его содержание. Для проверки смысла пригодятся практика человеческой проверки и руководство «от знаний к практике». Совпавший хеш определяет входные данные; человеку ещё нужно проверить точность ответа.

Поиск сейчас сопоставляет подстроки: перефразированный вопрос может не найти существующую статью. Поддерживаются английский и русский языки; отсутствующие переведённые поля могут заменяться английскими. Проверяйте сам текст вместе с выбранным языком.