Merge pull request #603 from kiwix/documentation

Documentation updates

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 <new-opds-api>`
+    -  ``/raw``
+    -  ``/search`` (with ``/search/searchdescription.xml``)
+
 .. _welcome-page:
 
 ``/``
 -----
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 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 <public-api-endpoint>`
+===== ===========
+
 The new OPDS API of ``kiwix-serve`` is based on the `OPDS Catalog specification
 v1.2 <https://specs.opds.io/opds-1.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 <new-opds-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 <new-opds-api>`
+===== ===========
+
 Describes the `/catalog/v2/entries`_ endpoint in `OpenSearch description format
 <https://developer.mozilla.org/en-US/docs/Web/OpenSearch>`_.
 
@@ -196,6 +251,10 @@ Describes the `/catalog/v2/entries`_ endpoint in `OpenSearch description format
 ``/catalog/v2/categories``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: member of a :ref:`public API <new-opds-api>`
+===== ===========
+
 Returns the full list of ZIM file categories as an `OPDS Navigation Feed
 <https://specs.opds.io/opds-1.2#22-navigation-feeds>`_.
 
@@ -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 <new-opds-api>`
+===== ===========
+
 Returns a full or filtered list of ZIM files as a paginated `OPDS acquisition
 feed <https://specs.opds.io/opds-1.2#23-acquisition-feeds>`_ with `complete
 entries
@@ -248,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
@@ -293,6 +359,10 @@ Examples:
 ``/catalog/v2/entry/ZIMID``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: member of a :ref:`public API <new-opds-api>`
+===== ===========
+
 Returns full info about the library entry with :term:`UUID <ZIM UUID>`
 ``ZIMID``.
 
@@ -300,6 +370,10 @@ Returns full info about the library entry with :term:`UUID <ZIM UUID>`
 ``/catalog/v2/illustration/ZIMID``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: member of a :ref:`public API <new-opds-api>`
+===== ===========
+
 **Usage:**
 
   ``/catalog/v2/illustration/ZIMID?size=N``
@@ -313,6 +387,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 <new-opds-api>`
+===== ===========
+
 Returns the full list of ZIM file languages as an `OPDS Navigation Feed
 <https://specs.opds.io/opds-1.2#22-navigation-feeds>`_.
 
@@ -320,6 +398,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 <new-opds-api>`
+===== ===========
+
 Returns the full or filtered list of ZIM files as an `OPDS acquisition feed
 <https://specs.opds.io/opds-1.2#23-acquisition-feeds>`_ with `partial entries
 <https://specs.opds.io/opds-1.2#512-partial-and-complete-catalog-entries>`_.
@@ -332,6 +414,10 @@ Supported filters are the same as for the `/catalog/v2/entries`_ endpoint.
 ``/catalog`` (Legacy OPDS API)
 ------------------------------
 
+===== ===========
+Type: :ref:`deprecated <deprecation>`
+===== ===========
+
 The legacy OPDS API is preserved for backward compatibility and is deprecated.
 :ref:`New OPDS API <new-opds-api>` should be used instead.
 
@@ -339,12 +425,20 @@ The legacy OPDS API is preserved for backward compatibility and is deprecated.
 ``/catalog/root.xml``
 ^^^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: member of a :ref:`deprecated API <legacy-opds-api>`
+===== ===========
+
 Full library OPDS catalog (list of all ZIM files).
 
 
 ``/catalog/searchdescription.xml``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: member of a :ref:`deprecated API <legacy-opds-api>`
+===== ===========
+
 Describes the `/catalog/search`_ endpoint in `OpenSearch description format
 <https://developer.mozilla.org/en-US/docs/Web/OpenSearch>`_.
 
@@ -352,6 +446,10 @@ Describes the `/catalog/search`_ endpoint in `OpenSearch description format
 ``/catalog/search``
 ^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: member of a :ref:`deprecated API <legacy-opds-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 +458,10 @@ search/filtering criteria. Supported filters are the same as for the
 ``/catch/external``
 -------------------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 **Usage:**
 
   ``/catch/external?source=URL``
@@ -384,12 +486,20 @@ resource.
 ``/content``
 ------------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 ZIM file content is served under the ``/content`` endpoint as described below.
 
 
 ``/content/ZIMNAME/PATH/IN/ZIMFILE``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 Returns the entry with path ``PATH/IN/ZIMFILE`` from ZIM file with :term:`name
 <ZIM name>` ``ZIMNAME``.
 
@@ -397,6 +507,10 @@ Returns the entry with path ``PATH/IN/ZIMFILE`` from ZIM file with :term:`name
 ``/content/ZIMNAME``
 ^^^^^^^^^^^^^^^^^^^^
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 ``/content/ZIMNAME`` redirects to the main page of the ZIM file with :term:`name
 <ZIM 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 +519,10 @@ path or path equal to ``/``, in which case that entry is returned).
 ``/random``
 -----------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 **Usage:**
 
   ``/random?content=ZIMNAME``
@@ -417,8 +535,25 @@ specified ZIM file.
   ``content``: :term:`name <ZIM name>` of the ZIM file.
 
 
+.. _raw:
+
+``/raw``
+--------
+
+===== ===========
+Type: :ref:`public <public-api-endpoint>`
+===== ===========
+
+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 <raw>`
+===== ===========
 
 Returns the entry with path ``PATH/IN/ZIMFILE`` from the ZIM file with
 :term:`name <ZIM name>` ``ZIMNAME``. Currently, this endpoint almost duplicates
@@ -427,11 +562,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 <public-api-endpoint>`, whereas ``/content`` is
+:ref:`private <private-api-endpoint>`.
 
 
 ``/raw/ZIMNAME/meta/METADATAID``
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+===== ===========
+Type: member of a :ref:`public API <raw>`
+===== ===========
 
 Returns the metadata item ``METADATAID`` from the ZIM file with :term:`name
 <ZIM name>` ``ZIMNAME``.
@@ -440,6 +581,10 @@ Returns the metadata item ``METADATAID`` from the ZIM file with :term:`name
 ``/search``
 -----------
 
+===== ===========
+Type: :ref:`public <public-api-endpoint>`
+===== ===========
+
 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.
@@ -465,7 +610,8 @@ A multi-ZIM search request must comply with the following constraints:
     present in the request, are simply ignored).
 
     ``content``: :term:`name <ZIM 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 <deprecation>`. ``books.name``
+    should be used instead.
 
     ``books.id``: :term:`UUID <ZIM UUID>` of the ZIM file. Can be repeated for
     a multi-ZIM search, however must respect the :ref:`multi-ZIM search
@@ -475,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 <multi-zim-search-constraints>`.
 
+    ``books.filter.{criteria}``: allows to take full advantage of :ref:`library
+    filtering <library-filtering>` functionality of the `/catalog/v2/entries`_
+    endpoint (``{criteria}`` must be replaced with an attribute/filtering
+    criteria name supported by :ref:`library filtering <library-filtering>`).
+
   Query parameters:
 
     ``pattern`` (optional; defaults to an empty string): text to search for.
@@ -494,11 +645,34 @@ 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``
 ---------------------------------
 
+===== ===========
+Type: :ref:`public <public-api-endpoint>`
+===== ===========
+
 Describes the `/search`_ endpoint in `OpenSearch description format
 <https://developer.mozilla.org/en-US/docs/Web/OpenSearch>`_.
 
@@ -507,6 +681,10 @@ Describes the `/search`_ endpoint in `OpenSearch description format
 ``/skin``
 -----------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 Static front-end resources (such as CSS, javascript and images) are all grouped
 under ``/skin``.
 
@@ -532,6 +710,10 @@ resources by using explicit ``cacheid`` s.
 ``/suggest``
 ------------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 **Usage:**
 
   ``/suggest?content=ZIMNAME[&term=QUERY][&count=N][&start=S]``
@@ -582,6 +764,10 @@ added as an option to perform a full text search in the said ZIM file.
 ``/viewer``
 -----------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 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 +775,10 @@ component of the URL as ``/viewer#ZIMNAME/PATH/IN/ZIMFILE``.
 ``/viewer_settings.js``
 -----------------------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 Settings of the ZIM file viewer that are configurable via certain command line
 options of ``kiwix-serve`` (e.g. ``--nolibrarybutton``).
 
@@ -596,6 +786,10 @@ options of ``kiwix-serve`` (e.g. ``--nolibrarybutton``).
 /ANYTHING/ELSE
 --------------
 
+===== ===========
+Type: :ref:`private <private-api-endpoint>`
+===== ===========
+
 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``.