docs: Add umapyoi.net API documentation

10 files changed, 301 insertions, 0 deletions

diff --git a/umapyoi_net_docs/character.rst b/umapyoi_net_docs/character.rst
new file mode 100644
index 0000000..c0a3fa2
--- /dev/null
+++ b/umapyoi_net_docs/character.rst
@@ -0,0 +1,53 @@
+Character Endpoints
+====================
+
+:ref:`routingtable`
+
+
+Sources
+-------
+English translation of character profiles:
+
+- `GameTora <https://gametora.com/umamusume>`_
+- `Noccu's Translation Project <https://github.com/noccu/umamusu-translate>`_
+
+
+Endpoints
+---------
+.. http:get:: /api/v1/character
+
+    Returns all character IDs.
+
+
+.. http:get:: /api/v1/character/info
+
+    Returns all characters' information.
+
+
+.. http:get:: /api/v1/character/list
+
+    Returns all characters' information needed for the list.
+
+
+.. http:get:: /api/v1/character/(int:chara_id)
+
+    Returns info of a character by ID.
+
+
+.. http:get:: /api/v1/character/images/(int:chara_id)
+
+    Returns a character's images by ID.
+
+
+.. http:get:: /api/v1/character/movies/(int:chara_id)
+
+    Returns a character's movies by ID.
+
+
+.. http:get:: /api/v1/character/context/(int:row_number)
+
+    Returns the row_number of the characters around given row_number.
+
+.. http:get:: /api/v1/character/currentbirthdays
+
+    Returns info about characters who currently have a birthday and the next day a character has a birthday.
diff --git a/umapyoi_net_docs/endpoints.rst b/umapyoi_net_docs/endpoints.rst
new file mode 100644
index 0000000..00b0e88
--- /dev/null
+++ b/umapyoi_net_docs/endpoints.rst
@@ -0,0 +1,12 @@
+API Endpoints
+=============
+
+.. toctree::
+    character
+    voiceactor
+    outfit
+    support
+    news
+    music
+    gacha
+    vpn
diff --git a/umapyoi_net_docs/gacha.rst b/umapyoi_net_docs/gacha.rst
new file mode 100644
index 0000000..d8c877d
--- /dev/null
+++ b/umapyoi_net_docs/gacha.rst
@@ -0,0 +1,27 @@
+Gacha Banner Endpoints
+======================
+
+:ref:`routingtable`
+
+The ``card_type`` field indicates the type of banner.Possible values are:
+
+* ``Outfit``
+* ``Support Card``
+
+**Note:** New banners in game updates may take up to a day or longer to appear because I need to manually update the game first.
+
+Endpoints
+---------
+.. http:get:: /api/v1/gacha
+
+    Returns a list of all gacha banners with some basic info.
+
+
+.. http:get:: /api/v1/gacha/(int:gacha_id)
+
+    Returns more detailed information about a specific gacha banner, including outfit/support card details.
+
+
+.. http:get:: /api/v1/gacha/current
+
+    Returns detailed information about the current gacha banner(s).
diff --git a/umapyoi_net_docs/index.rst b/umapyoi_net_docs/index.rst
new file mode 100644
index 0000000..81346ec
--- /dev/null
+++ b/umapyoi_net_docs/index.rst
@@ -0,0 +1,32 @@
+Welcome to Umapyoi.net's documentation!
+=======================================
+
+**Umapyoi.net** is a public API that provides information about `Uma Musume`_.
+Check out the :doc:`character` section for how to use the Characters endpoints.
+
+.. _Uma Musume: https://umamusume.jp/
+
+.. note::
+   This project is currently under active development.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   endpoints
+
+Rate limits
+###########
+
+The current API rate limits are as follows:
+
+* 10 requests per second
+* 500 requests per minute
+* 7.200 requests per hour
+* 172.800 requests per day
+
+Indices and tables
+==================
+
+* :ref:`routingtable`
+* :ref:`search`
diff --git a/umapyoi_net_docs/music.rst b/umapyoi_net_docs/music.rst
new file mode 100644
index 0000000..975c926
--- /dev/null
+++ b/umapyoi_net_docs/music.rst
@@ -0,0 +1,36 @@
+Music Endpoints
+===============
+
+:ref:`routingtable`
+
+Endpoints
+---------
+.. http:get:: /api/v1/music/min/albums
+
+    Returns a list of all albums (minimal versions).
+
+
+.. http:get:: /api/v1/music/min/albums/(int:page)
+
+    Returns a paginated list of albums. (10 per page, minimal)
+    Page 0 is the first page.
+
+
+.. http:get:: /api/v1/music/album/(int:album_id)
+
+    Returns the album with the given id.
+
+
+.. http:get:: /api/v1/music/filters
+
+    Returns a list of all filters.
+
+
+.. http:get:: /api/v1/music/filter
+
+    Returns a list of all songs with their associated albums and/or albums with their associated songs that match the given filter(s).
+    Filters are provided using URL parameters. Multiple filters of the same type are ANDed and should be separated by ``~`` in the URL.
+
+    Use key ``search`` to search for a song name or album name.
+
+    Example: ``/api/v1/music/filter?character=special-week~silence-suzuka&song=umapyoi-densetsu``
diff --git a/umapyoi_net_docs/news.rst b/umapyoi_net_docs/news.rst
new file mode 100644
index 0000000..d40df0f
--- /dev/null
+++ b/umapyoi_net_docs/news.rst
@@ -0,0 +1,51 @@
+News Endpoints
+==============
+
+:ref:`routingtable`
+
+Endpoints
+---------
+.. http:get:: /api/v1/news
+
+    Returns all news post IDs.
+
+
+.. http:get:: /api/v1/news/(int:post_id)
+
+    Returns a news post by ID.
+
+
+.. http:get:: /api/v1/news/(int:post_id)/source
+
+    Redirect to the original news post on umamusume.jp.
+
+
+.. http:get:: /api/v1/news/latest/(int:count)
+
+    Returns the latest n amount of posts. n <= 32
+
+
+.. http:get:: /api/v1/news/latest/(int:count)/(int:offset)
+
+    Returns the latest n amount of posts, offset by specified amount. n <= 32
+
+
+.. http:get:: /api/v1/news/latest/(int:count)/label/(int:label)
+
+    Returns the latest n amount of posts of a particular label. n <= 32
+
+
+.. http:get:: /api/v1/news/latest/(int:count)/(int:offset)/label/(int:label)
+
+    Returns the latest n amount of posts of a particular label, offset by specified amount. n <= 32
+
+
+.. http:get:: /api/v1/news/search/(query)
+
+    Returns sorted news articles which include one or more search terms from a URL-encoded string (separated by space).
+    Query string length must be 200 characters or less.
+
+
+.. http:get:: /api/v1/news/context/(int:row_number)
+
+    Returns the row_number of the posts around given row_number.
diff --git a/umapyoi_net_docs/outfit.rst b/umapyoi_net_docs/outfit.rst
new file mode 100644
index 0000000..6ddac9c
--- /dev/null
+++ b/umapyoi_net_docs/outfit.rst
@@ -0,0 +1,25 @@
+Outfit Endpoints
+================
+
+:ref:`routingtable`
+
+An outfit is otherwise called "Character" on GameTora, but umapyoi.net makes a distinction between characters and their outfits.
+A character might have multiple outfits.
+
+Endpoints
+---------
+.. http:get:: /api/v1/outfit
+
+    Returns all outfit IDs. (Each support card has an id and gametora identifier.)
+
+.. http:get:: /api/v1/outfit/(int:outfit_id)
+
+    Returns outfit data by ID.
+
+.. http:get:: /api/v1/outfit/character/(int:chara_id)
+
+    Returns outfit data belonging to a given character ID (game_id).
+
+.. http:get:: /api/v1/outfit/(int:outfit_id)/gametora
+
+    Redirect to the GameTora page of an outfit.
diff --git a/umapyoi_net_docs/support.rst b/umapyoi_net_docs/support.rst
new file mode 100644
index 0000000..54a0c1a
--- /dev/null
+++ b/umapyoi_net_docs/support.rst
@@ -0,0 +1,22 @@
+Support Card Endpoints
+======================
+
+:ref:`routingtable`
+
+Endpoints
+---------
+.. http:get:: /api/v1/support
+
+    Returns all support card IDs. (Each support card has an id, chara_id (game_id) and gametora identifier.)
+
+.. http:get:: /api/v1/support/(int:support_id)
+
+    Returns support card data by ID.
+
+.. http:get:: /api/v1/support/character/(int:chara_id)
+
+    Returns all support card data belonging to a given character ID (game_id).
+
+.. http:get:: /api/v1/support/(int:support_id)/gametora
+
+    Redirect to the GameTora page of a support card ID.
diff --git a/umapyoi_net_docs/voiceactor.rst b/umapyoi_net_docs/voiceactor.rst
new file mode 100644
index 0000000..e65f0b4
--- /dev/null
+++ b/umapyoi_net_docs/voiceactor.rst
@@ -0,0 +1,18 @@
+Voice Actor Endpoints
+=====================
+
+:ref:`routingtable`
+
+Endpoints
+---------
+.. http:get:: /api/v1/va/(int:va_id)
+
+    Returns a dictionary with info of a voice actor of given ID.
+
+.. http:get:: /api/v1/va/character/(int:chara_id)
+
+    Returns a list of voice actor IDs for a given character ID.
+
+.. http:get:: /api/v1/va/socials/(int:va_id)
+
+    Returns a list of socials for a voice actor of given ID.
diff --git a/umapyoi_net_docs/vpn.rst b/umapyoi_net_docs/vpn.rst
new file mode 100644
index 0000000..076615e
--- /dev/null
+++ b/umapyoi_net_docs/vpn.rst
@@ -0,0 +1,25 @@
+VPN Endpoints
+=============
+
+:ref:`routingtable`
+
+Umapyoi.net automatically tests VPNs to see if they work with DMM and CyGames.
+
+URLs used to verify:
+
+* DMM (for login): `https://bitcoin.dmm.com/ <https://bitcoin.dmm.com/>`_
+* CyGames (for the game): `https://api-umamusume.cygames.jp/ <https://api-umamusume.cygames.jp/>`_
+
+
+Endpoints
+---------
+.. http:get:: /api/v1/vpn/dmm
+
+    Gets VPNs that were recently verified to work with DMM.
+    Sorted by ping time.
+
+
+.. http:get:: /api/v1/vpn/cygames
+
+    Gets VPNs that were recently verified to work with CyGames and DMM.
+    Sorted by ping time to CyGames.