mirror of
https://github.com/kiwix/kiwix-tools.git
synced 2025-09-22 03:12:20 -04:00
Kelson
GitHub
commit
688bb356ea
@ -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``.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user