User:MHolloway (WMF)/Drafts/Compilation endoint schema

From mediawiki.org

To support offline article compilations on the mobile platforms, the Readers team needs a service to provide information on the compilations currently available. This page is for discussing and finalizing its proposed structure.

Similar to the announcements endpoint, the compilations endpoint response will have a top-level compilations property:

{
  compilations": []
}

When compilations are made available, the compilations array will be populated with a set of Compilation objects, one for each compilation to be made available for in-app download, defined as follows:

Compilation[edit]

Property Type Required From ZIM metadata Description Example
name String Yes Yes A human-readable name for the compilation "Ray Charles (June 2015)"
url String Yes No A download URL for the compilation file "https://download.kiwix.org/zim/wikipedia_en_ray_charles_maxi.zim"
lang String[] No Yes A list of wiki language codes documenting the language(s) of the content contained in the compilation. ["en", "de"]
summary String No Yes A short description of the compilation contents "Articles from the English Wikipedia related to the musician Ray Charles"
description String No * A detailed description of the compilation contents "A collection of articles with images from the English Wikipedia related to the musician Ray Charles, compiled in June 2016"
media Enum No * A description of the media contained in the compilation. One of "all" (contains images, audio, and video), "nopic" (contains images but no audio or video), or "novid" (no images, audio, or video). "all"
image_thumb Image No No A thumbnail-sized image pertaining to the compilation's contents. URL should be for the 320px width, if available. "https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Ray_Charles.jpg/320px-Ray_Charles.jpg"
image_feature Image No No A feature-size image pertaining to the compilation's contents. URL should be for the 640px width, if available. "https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Ray_Charles.jpg/640px-Ray_Charles.jpg"
count Integer Yes Yes (in file header) The number of articles included in the compilation 9999
size Integer Yes No The size of the compilation, in bytes 1043986445
date String Yes Yes The date of the compilation file in ISO 8601 format "2015-06-02"

* Denotes potential fields to be added to supported ZIM metadata

where Image is defined as:

Image[edit]

Property Type Required Description
url String Yes The image file's download URL
width Integer Yes The image width, in pixels
height Integer Yes The image height, in pixels