View history

Edit

API

Introduction

Applications rely on the Pepper&Carrot website providing an API to function. This file documents the current API.

Downloadable files

The Pepper&Carrot official website provides directories containing translated comic art. This section specifies the paths generated so they can be used for downloads.

The path to the directory containing translated image files is: <site>/<episode>/<res>/, where:

• <site> is renderfarm output (local or https://peppercarrot.com/0_sources)
• <episode> is the episode directory name.
• <res> is either hi-res or low-res.
• Directories contain a collection of images for each translated language:
  • The episode pages, numbered from 00 to total_pages.
  • The episode's cover page.

The path to the directory containing untranslated image files is: <translated-dir>/gfx-only, where:

• <translated-dir> is the directory containing translated image files.
• Only the untranslated gfx language code is available in this directory.

The format used for episode directory names is: ep<number>_<title>, where:

• <number> is the episode's number.
• <title> is the name of the episode.

The format used for image files is: <lang>_Pepper-and-Carrot_by-David-Revoy_E<episode>[P<page>].<ext>, where:

• <lang> is a Pepper&Carrot language code.
• <episode> is the number of the episode.
• <page> is the number of the page, starting at 0.
• <ext> is jpg or gif.
• The P<page> field is not present for episode cover images.

To make parsing and generation easier, these constraints apply to all paths:

• Fields only contain alphanumeric characters and dashes.
• Numbers are positive integers.
• Numbers under 10 are padded to two digits.

JSON episode index

This index dictates which downloadable comic pages are available. The generate-json-episodes-list.py script generates this file. The file is then published at: https://peppercarrot.com/0_sources/episodes.json

The index contains the following data:

• A list of comic episodes.
• Each episode's directory name.
• Each episode's available translations.
• Each episode's page count.

The schema is formatted like this (excluding Python comments):

[ # JSON list of episode objects sorted from oldest to newest
    # older episodes omitted
    { # JSON object representing a episode
        "translated_languages": [
            # JSON list of languages the page is currently translated to
            # The list is sorted alphabetically
            # Each entry is a JSON string with a Pepper&Carrot language code
            # These codes are consistent among episodes but not standardized
            # If you need a mapping to ISO 631 versions see lang.json in:
            # https://github.com/qtwyeuritoiy/peppercarrot-metadata
            "cn",
            "de",
            "en",
            # other languages omitted
        ],
        "total_pages": 8,
            # JSON integer specifying the page count excluding the credits page
            # If you want a true page count, add 1 for the credits
        "name": "ep24_The-Unity-Tree"
            # JSON string containing the directory name of the episode
    },
    # newer episodes omitted
]

The index will only list complete sets of translated downloadable files. A set is considered complete if:

• A cover is available.
• All pages are available.
• Hi-res and low-res versions are available.

Example usage

The following fields are chosen by the application:

• dir = ep24_The-Unity-Tree found in the JSON data's name field
• lang = en selected from the JSON data's translated_languages field
• episode = 24 number field parsed from the dir field
• page = 7 selected from 0 to total_pages inclusive
• res = low-res user prefered
• ext = jpg assumed

The directory path and filename can be generated from the above fields: https://peppercarrot.com/0_sources/ep24_The-Unity-Tree/low-res/en_Pepper-and-Carrot_by-David-Revoy_E24P07.jpg

Added together these generate a usable URL for an application.

Modifying the API

The process of adding to the API goes like this:

1. Create a fake testing API containing your additions.
2. Modify your application to use to use the testing API additions.
3. Ensure the API works and fits your purpose.
4. Document the additions in this document.
5. Send a merge request.
6. Listen to feedback and change API if needed.
7. Repeat process until merge or rejection.
8. Once the production API is updated, use that instead of the testing API.

Altering the existing API is likely to break existing applications. To prevent this, any evolution of the API must output a different JSON files versioned.

View history

Edit