Commit 00a21fda authored by Jookia's avatar Jookia
Browse files

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.
parent 078bdf02
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:
``<site>/<dir>/<res>/<lang>_<filename>``, where:
- ``<site>`` is renderfarm output (local or https://peppercarrot.com/0_sources)
- ``<dir>`` is the episode directory name
- ``<res>`` is either hi-res or low-res
- ``<lang>`` is the Pepper&Carrot language code for the page translation
- ``<filename>`` 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).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment