User:MHolloway (WMF)/Drafts/Compilation endoint schema
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 |