From 00a21fdac6723b3d839cbd9cca16c2d60a369744 Mon Sep 17 00:00:00 2001 From: Jookia <166291@gmail.com> Date: Fri, 9 Nov 2018 12:22:05 +1100 Subject: [PATCH] Add API v2 spec The main difference between this and API v1 is that instead of inferring filenames based on episode and page numbers, it now directly specifies filenames. This allows for episodes by other authors and proper GIF support. --- 131_API2.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 131_API2.md diff --git a/131_API2.md b/131_API2.md new file mode 100644 index 0000000..3423126 --- /dev/null +++ b/131_API2.md @@ -0,0 +1,115 @@ +API v2 +====== + +Introduction +------------ + +Applications rely on the Pepper&Carrot website providing an API to function. +This file documents the API v2. + +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 episode pages are: +``///_``, where: + - ```` is renderfarm output (local or https://peppercarrot.com/0_sources) + - ```` is the episode directory name + - ```` is either hi-res or low-res + - ```` is the Pepper&Carrot language code for the page translation + - ```` is the filename for the comic page from the index + +JSON episode index +------------------ + +This index dictates which downloadable comic pages are available. +The index is published at: https://peppercarrot.com/0_sources/episodes-v2.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 filename suffixes + +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 + "translations": [ + # JSON list of languages the episode 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 + ], + "filenames": { + # JSON object containing episode page filenames + "comic": [ + # JSON list of episode comic page filenames + # The list is sorted first to last + # Each entry is a JSON string + "Pepper-and-Carrot_by-David-Revoy_E04P01.jpg", + "Pepper-and-Carrot_by-David-Revoy_E04P02.jpg", + "Pepper-and-Carrot_by-David-Revoy_E04P03.jpg", + "Pepper-and-Carrot_by-David-Revoy_E04P04.jpg", + "Pepper-and-Carrot_by-David-Revoy_E04P05.gif", + "Pepper-and-Carrot_by-David-Revoy_E04P06.jpg", + "Pepper-and-Carrot_by-David-Revoy_E04P07.jpg" + ], + "title": "Pepper-and-Carrot_by-David-Revoy_E04P00.jpg", + # JSON string containing the episode title image filename + "cover": "Pepper-and-Carrot_by-David-Revoy_E04.jpg", + # JSON string containing the episode cover image filename + "credits": "Pepper-and-Carrot_by-David-Revoy_E04P08.jpg" + # JSON string containing the episode credits image filename + } + "directory": "ep04_Stroke-of-genius" + # JSON string containing the directory the comic is in + }, + # 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: + - ``site = https://www.peppercarrot.com/0_sources`` + - ``dir = ep04_Stroke-of-genius`` found in the episode index + - ``res = low-res`` chosen to save bandwidth + - ``lang = en`` selected from the episode index translations field + - ``file = Pepper-and-Carrot_by-David-Revoy_E04.jpg`` chosen to show + +The directory path and filename can be generated from the above fields: + https://www.peppercarrot.com/0_sources/ep04_Stroke-of-genius/low-res/en_Pepper-and-Carrot_by-David-Revoy_E04.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. ( https://peppercarrot.com/0_sources/episodes-v1.json is the evolution of https://peppercarrot.com/0_sources/episodes.json). -- GitLab