From 6ab6abc6d3eb8bcdbf0720c55ce4c8e7e43eb184 Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Sat, 11 Feb 2023 11:20:32 +0100 Subject: [PATCH 1/2] Noted the HTTP API type (public/private) in the docs --- docs/kiwix-serve.rst | 172 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 169 insertions(+), 3 deletions(-) diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst index acb49fc..e5fe905 100644 --- a/docs/kiwix-serve.rst +++ b/docs/kiwix-serve.rst @@ -154,11 +154,54 @@ HTTP API HTTP API endpoints presented below are relative to that location, i.e. ``/foo/bar`` must be actually accessed as ``http://ADDR:PORT/ROOT/foo/bar``. +.. note:: + + The HTTP API is documented in its entirety in order to facilitate the work of + the Kiwix development team. Note, however, that only a subset of the HTTP API + constitutes ``kiwix-serves``'s public interface. + + .. _public-api-endpoint: + + **Public API endpoint** + + A public HTTP API endpoint is intended to serve the outside world (in + addition to ``kiwix-serve``'s front-end and other Kiwix products). The + Kiwix development team will do its best to ensure gratifying experience for + clients of public API endpoints at all stages of the endpoint lifecycle. + + .. _private-api-endpoint: + + **Private API endpoint** + + A private API endpoint is intended to be used only by ``kiwix-serve``'s + frontend or by other products maintained solely by the Kiwix team. Private + API comes without any guaranees. It may change as frequently and as + drasticaly as the Kiwix development team sees fit. + + .. _deprecation: + + **Deprecation** + + Public API doesn't stay frozen once and forever. As the API evolves, Kiwix + team reserves the right to drop support for certain old functionality. In + such events, an advance notice will be issued and the users will be given + enough time to prepare for the change. + + Currently, public endpoints are limited to the following list: + + - :ref:`OPDS API ` + - ``/raw`` + - ``/search`` (with ``/search/searchdescription.xml``) + .. _welcome-page: ``/`` ----- +===== =========== +Type: :ref:`private ` +===== =========== + Welcome page is served under ``/``. By default this is the library page, where books are listed and can be looked up/filtered interactively. However, the welcome page can be overriden through the :option:`--customIndex`/:option:`-c` @@ -170,6 +213,10 @@ command line option of ``kiwix-serve``. ``/catalog/v2`` (OPDS API) ------------------------------ +===== =========== +Type: :ref:`public ` +===== =========== + The new OPDS API of ``kiwix-serve`` is based on the `OPDS Catalog specification v1.2 `_. All of its endpoints are grouped under ``/catalog/v2``. @@ -181,6 +228,10 @@ compatibility. ``/catalog/v2/root.xml`` ^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + The OPDS Catalog Root links to the OPDS acquisition and navigation feeds accessible through the other endpoints of the OPDS API. @@ -188,6 +239,10 @@ accessible through the other endpoints of the OPDS API. ``/catalog/v2/searchdescription.xml`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + Describes the `/catalog/v2/entries`_ endpoint in `OpenSearch description format `_. @@ -196,6 +251,10 @@ Describes the `/catalog/v2/entries`_ endpoint in `OpenSearch description format ``/catalog/v2/categories`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + Returns the full list of ZIM file categories as an `OPDS Navigation Feed `_. @@ -203,6 +262,10 @@ Returns the full list of ZIM file categories as an `OPDS Navigation Feed ``/catalog/v2/entries`` ^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + Returns a full or filtered list of ZIM files as a paginated `OPDS acquisition feed `_ with `complete entries @@ -293,6 +356,10 @@ Examples: ``/catalog/v2/entry/ZIMID`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + Returns full info about the library entry with :term:`UUID ` ``ZIMID``. @@ -300,6 +367,10 @@ Returns full info about the library entry with :term:`UUID ` ``/catalog/v2/illustration/ZIMID`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + **Usage:** ``/catalog/v2/illustration/ZIMID?size=N`` @@ -313,6 +384,10 @@ If no illustration of requested size is found a HTTP 404 error is returned. ``/catalog/v2/languages`` ^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + Returns the full list of ZIM file languages as an `OPDS Navigation Feed `_. @@ -320,6 +395,10 @@ Returns the full list of ZIM file languages as an `OPDS Navigation Feed ``/catalog/v2/partial_entries`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`public API ` +===== =========== + Returns the full or filtered list of ZIM files as an `OPDS acquisition feed `_ with `partial entries `_. @@ -332,6 +411,10 @@ Supported filters are the same as for the `/catalog/v2/entries`_ endpoint. ``/catalog`` (Legacy OPDS API) ------------------------------ +===== =========== +Type: :ref:`deprecated ` +===== =========== + The legacy OPDS API is preserved for backward compatibility and is deprecated. :ref:`New OPDS API ` should be used instead. @@ -339,12 +422,20 @@ The legacy OPDS API is preserved for backward compatibility and is deprecated. ``/catalog/root.xml`` ^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`deprecated API ` +===== =========== + Full library OPDS catalog (list of all ZIM files). ``/catalog/searchdescription.xml`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`deprecated API ` +===== =========== + Describes the `/catalog/search`_ endpoint in `OpenSearch description format `_. @@ -352,6 +443,10 @@ Describes the `/catalog/search`_ endpoint in `OpenSearch description format ``/catalog/search`` ^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: member of a :ref:`deprecated API ` +===== =========== + Returns the list of ZIM files (in OPDS catalog format) matching the search/filtering criteria. Supported filters are the same as for the `/catalog/v2/entries`_ endpoint. @@ -360,6 +455,10 @@ search/filtering criteria. Supported filters are the same as for the ``/catch/external`` ------------------- +===== =========== +Type: :ref:`private ` +===== =========== + **Usage:** ``/catch/external?source=URL`` @@ -384,12 +483,20 @@ resource. ``/content`` ------------ +===== =========== +Type: :ref:`private ` +===== =========== + ZIM file content is served under the ``/content`` endpoint as described below. ``/content/ZIMNAME/PATH/IN/ZIMFILE`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: :ref:`private ` +===== =========== + Returns the entry with path ``PATH/IN/ZIMFILE`` from ZIM file with :term:`name ` ``ZIMNAME``. @@ -397,6 +504,10 @@ Returns the entry with path ``PATH/IN/ZIMFILE`` from ZIM file with :term:`name ``/content/ZIMNAME`` ^^^^^^^^^^^^^^^^^^^^ +===== =========== +Type: :ref:`private ` +===== =========== + ``/content/ZIMNAME`` redirects to the main page of the ZIM file with :term:`name ` ``ZIMNAME`` (unless that ZIM file contains an entry with an empty path or path equal to ``/``, in which case that entry is returned). @@ -405,6 +516,10 @@ path or path equal to ``/``, in which case that entry is returned). ``/random`` ----------- +===== =========== +Type: :ref:`private ` +===== =========== + **Usage:** ``/random?content=ZIMNAME`` @@ -417,8 +532,25 @@ specified ZIM file. ``content``: :term:`name ` of the ZIM file. +.. _raw: + +``/raw`` +-------- + +===== =========== +Type: :ref:`public ` +===== =========== + +The ``/raw`` API provides access to ZIM file data. It consists of two separate +endpoints for accessing data and metadata. + + ``/raw/ZIMNAME/content/PATH/IN/ZIMFILE`` ----------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +===== =========== +Type: member of a :ref:`public API ` +===== =========== Returns the entry with path ``PATH/IN/ZIMFILE`` from the ZIM file with :term:`name ` ``ZIMNAME``. Currently, this endpoint almost duplicates @@ -427,11 +559,17 @@ Returns the entry with path ``PATH/IN/ZIMFILE`` from the ZIM file with ``/raw`` endpoint guarantees that no server-side processing will be applied to the returned content, whereas content obtained via the ``/content`` endpoint may in the future undergo some processing intended to improve the operation of -the viewer (e.g. compensating for certain bugs in ZIM creation). +the viewer (e.g. compensating for certain bugs in ZIM creation). Also note that +``/raw`` is :ref:`public `, whereas ``/content`` is +:ref:`private `. ``/raw/ZIMNAME/meta/METADATAID`` --------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +===== =========== +Type: member of a :ref:`public API ` +===== =========== Returns the metadata item ``METADATAID`` from the ZIM file with :term:`name ` ``ZIMNAME``. @@ -440,6 +578,10 @@ Returns the metadata item ``METADATAID`` from the ZIM file with :term:`name ``/search`` ----------- +===== =========== +Type: :ref:`public ` +===== =========== + Performs a full text search on one or more ZIM files and returns an HTML page with a list of links to matching pages along with snippets of the matching portions of those pages. @@ -499,6 +641,10 @@ A multi-ZIM search request must comply with the following constraints: ``/search/searchdescription.xml`` --------------------------------- +===== =========== +Type: :ref:`public ` +===== =========== + Describes the `/search`_ endpoint in `OpenSearch description format `_. @@ -507,6 +653,10 @@ Describes the `/search`_ endpoint in `OpenSearch description format ``/skin`` ----------- +===== =========== +Type: :ref:`private ` +===== =========== + Static front-end resources (such as CSS, javascript and images) are all grouped under ``/skin``. @@ -532,6 +682,10 @@ resources by using explicit ``cacheid`` s. ``/suggest`` ------------ +===== =========== +Type: :ref:`private ` +===== =========== + **Usage:** ``/suggest?content=ZIMNAME[&term=QUERY][&count=N][&start=S]`` @@ -582,6 +736,10 @@ added as an option to perform a full text search in the said ZIM file. ``/viewer`` ----------- +===== =========== +Type: :ref:`private ` +===== =========== + ZIM file viewer. The ZIM file and entry therein must be specified via the hash component of the URL as ``/viewer#ZIMNAME/PATH/IN/ZIMFILE``. @@ -589,6 +747,10 @@ component of the URL as ``/viewer#ZIMNAME/PATH/IN/ZIMFILE``. ``/viewer_settings.js`` ----------------------- +===== =========== +Type: :ref:`private ` +===== =========== + Settings of the ZIM file viewer that are configurable via certain command line options of ``kiwix-serve`` (e.g. ``--nolibrarybutton``). @@ -596,6 +758,10 @@ options of ``kiwix-serve`` (e.g. ``--nolibrarybutton``). /ANYTHING/ELSE -------------- +===== =========== +Type: :ref:`private ` +===== =========== + Any other URL is considered as an attempt to access ZIM file content using the legacy URL scheme and is redirected to ``/content/ANYTHING/ELSE``. From d398ebdb3e707b9ff2505114bdee982f345ed2c8 Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Sat, 11 Feb 2023 12:04:18 +0100 Subject: [PATCH 2/2] Added missing information about /search endpoint --- docs/kiwix-serve.rst | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst index e5fe905..e38ab80 100644 --- a/docs/kiwix-serve.rst +++ b/docs/kiwix-serve.rst @@ -311,6 +311,9 @@ Examples: # Returns all entries starting from entry # 100 $ curl 'http://localhost:8080/catalog/v2/entries?start=100&count=-1' + +.. _library-filtering: + **Filtering:** A filtered subset of the library can be requested by providing one or more @@ -607,7 +610,8 @@ A multi-ZIM search request must comply with the following constraints: present in the request, are simply ignored). ``content``: :term:`name ` of the ZIM file (for a single-ZIM - search). This is a legacy parameter. ``books.name`` should be used instead. + search). This is a :ref:`legacy parameter `. ``books.name`` + should be used instead. ``books.id``: :term:`UUID ` of the ZIM file. Can be repeated for a multi-ZIM search, however must respect the :ref:`multi-ZIM search @@ -617,6 +621,11 @@ A multi-ZIM search request must comply with the following constraints: for a multi-ZIM search, however must respect the :ref:`multi-ZIM search constraints `. + ``books.filter.{criteria}``: allows to take full advantage of :ref:`library + filtering ` functionality of the `/catalog/v2/entries`_ + endpoint (``{criteria}`` must be replaced with an attribute/filtering + criteria name supported by :ref:`library filtering `). + Query parameters: ``pattern`` (optional; defaults to an empty string): text to search for. @@ -636,6 +645,25 @@ A multi-ZIM search request must comply with the following constraints: with entry # ``start`` from the full list of search results (the first result is assumed to have index 1). + Other parameters: + + ``format`` (optional, default: html): format of the search results. Allowed + values are: html, xml. + +Examples: + +.. code:: sh + + # Search for 'android' in the book with name 'scifi-library' + # Return results ## 51-60. + $ curl 'http://localhost:8080/search?pattern=android&books.name=scifi-library&start=51&pageLength=10' + + # Search for 'napoli' in books in Italian + $ curl 'http://localhost:8080/search?books.filter.lang=ita&pattern=napoli' + + # Search for 'chateau' in books in French that have a category of 'wikipedia'. + # Return the results as XML. + $ curl 'http://localhost:8080/search?pattern=chateau&books.filter.lang=fra&books.filter.category=wikipedia&format=xml' ``/search/searchdescription.xml``