From 281f37a483a6709ee78744d6c48923266ccdd6a0 Mon Sep 17 00:00:00 2001 From: lifegpc Date: Mon, 5 May 2025 22:36:12 +0800 Subject: [PATCH] Add vndb.json --- vndb.json | 967 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 967 insertions(+) create mode 100644 vndb.json diff --git a/vndb.json b/vndb.json new file mode 100644 index 0000000..e472064 --- /dev/null +++ b/vndb.json @@ -0,0 +1,967 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "VNDB.org API v2 (Kana)", + "description": "This API allows querying information from the VNDB database and managing user lists. This version replaces the old TCP-based API. The service is free for non-commercial use and provided on a best-effort basis, with rate limits of 200 requests per 5 minutes and 1 second of execution time per minute. Requests taking longer than 3 seconds will be aborted.", + "version": "2.0.0", + "license": { + "name": "Data License", + "url": "https://vndb.org/d14" + }, + "contact": { + "email": "contact@vndb.org", + "url": "https://vndb.org" + } + }, + "servers": [ + { + "url": "https://api.vndb.org/kana", + "description": "Main API endpoint" + }, + { + "url": "https://beta.vndb.org/api/kana", + "description": "Sandbox endpoint for testing and development" + } + ], + "tags": [ + { + "name": "Simple Requests", + "description": "Basic endpoints that don't require complex query structures" + }, + { + "name": "Database Querying", + "description": "Endpoints for searching and retrieving database entries" + }, + { + "name": "List Management", + "description": "Endpoints for managing user lists, requires authentication" + } + ], + "paths": { + "/schema": { + "get": { + "tags": ["Simple Requests"], + "summary": "Get API schema metadata", + "description": "Returns a JSON object with metadata about API objects, including enumeration values, available fields for querying, and supported external links.", + "operationId": "getSchema", + "responses": { + "200": { + "description": "JSON object with API schema metadata", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + } + } + } + }, + "/stats": { + "get": { + "tags": ["Simple Requests"], + "summary": "Get database statistics", + "description": "Returns overall database statistics including counts of various entry types.", + "operationId": "getStats", + "responses": { + "200": { + "description": "Database statistics", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "chars": { + "type": "integer", + "description": "Number of characters in the database" + }, + "producers": { + "type": "integer", + "description": "Number of producers in the database" + }, + "releases": { + "type": "integer", + "description": "Number of releases in the database" + }, + "staff": { + "type": "integer", + "description": "Number of staff entries in the database" + }, + "tags": { + "type": "integer", + "description": "Number of tags in the database" + }, + "traits": { + "type": "integer", + "description": "Number of traits in the database" + }, + "vn": { + "type": "integer", + "description": "Number of visual novels in the database" + } + } + } + } + } + } + } + } + }, + "/user": { + "get": { + "tags": ["Simple Requests"], + "summary": "Look up users by ID or username", + "description": "Returns information about users specified by IDs or usernames.", + "operationId": "getUser", + "parameters": [ + { + "name": "q", + "in": "query", + "description": "User ID or username to look up (can be specified multiple times)", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "fields", + "in": "query", + "description": "Comma-separated list of fields to select (id and username are always included)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Object with user information", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "null" + }, + { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "User ID in 'u123' format" + }, + "username": { + "type": "string", + "description": "Username" + }, + "lengthvotes": { + "type": "integer", + "description": "Number of play time votes submitted by this user" + }, + "lengthvotes_sum": { + "type": "integer", + "description": "Sum of the user's play time votes, in minutes" + } + }, + "required": ["id", "username"] + } + ] + } + } + } + } + }, + "400": { + "description": "Invalid request" + } + } + } + }, + "/authinfo": { + "get": { + "tags": ["Simple Requests"], + "summary": "Get information about the authenticated user", + "description": "Validates and returns information about the provided API token", + "operationId": "getAuthInfo", + "security": [ + { + "tokenAuth": [] + } + ], + "responses": { + "200": { + "description": "Authentication information", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "User ID" + }, + "username": { + "type": "string", + "description": "Username" + }, + "permissions": { + "type": "array", + "description": "Permissions granted to this token", + "items": { + "type": "string", + "enum": ["listread", "listwrite"] + } + } + }, + "required": ["id", "username", "permissions"] + } + } + } + }, + "401": { + "description": "Invalid authentication token" + } + } + } + }, + "/vn": { + "post": { + "tags": ["Database Querying"], + "summary": "Query visual novel entries", + "description": "Search for and retrieve visual novel entries based on filters", + "operationId": "queryVn", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Visual novel query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/release": { + "post": { + "tags": ["Database Querying"], + "summary": "Query release entries", + "description": "Search for and retrieve release entries based on filters", + "operationId": "queryRelease", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Release query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/producer": { + "post": { + "tags": ["Database Querying"], + "summary": "Query producer entries", + "description": "Search for and retrieve producer entries based on filters", + "operationId": "queryProducer", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Producer query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/character": { + "post": { + "tags": ["Database Querying"], + "summary": "Query character entries", + "description": "Search for and retrieve character entries based on filters", + "operationId": "queryCharacter", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Character query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/staff": { + "post": { + "tags": ["Database Querying"], + "summary": "Query staff entries", + "description": "Search for and retrieve staff entries based on filters", + "operationId": "queryStaff", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Staff query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/tag": { + "post": { + "tags": ["Database Querying"], + "summary": "Query tag entries", + "description": "Search for and retrieve tag entries based on filters", + "operationId": "queryTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Tag query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/trait": { + "post": { + "tags": ["Database Querying"], + "summary": "Query trait entries", + "description": "Search for and retrieve trait entries based on filters", + "operationId": "queryTrait", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Trait query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/quote": { + "post": { + "tags": ["Database Querying"], + "summary": "Query visual novel quotes", + "description": "Search for and retrieve quotes from visual novels", + "operationId": "queryQuote", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Quote query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/ulist": { + "post": { + "tags": ["List Management"], + "summary": "Query a user's visual novel list", + "description": "Fetch entries from a user's visual novel list based on filters", + "operationId": "getUserList", + "security": [ + { + "tokenAuth": [] + }, + {} + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/QueryRequest" + }, + { + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "User ID to fetch the list for (defaults to authenticated user)" + } + } + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "User list query results", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + }, + "400": { + "description": "Invalid request" + }, + "401": { + "description": "Authentication required for private lists" + }, + "429": { + "description": "Rate limit exceeded" + } + } + } + }, + "/ulist_labels": { + "get": { + "tags": ["List Management"], + "summary": "Get user list labels", + "description": "Fetch list labels for a user", + "operationId": "getUserListLabels", + "security": [ + { + "tokenAuth": [] + }, + {} + ], + "parameters": [ + { + "name": "user", + "in": "query", + "description": "User ID to fetch labels for (defaults to authenticated user)", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "fields", + "in": "query", + "description": "Fields to select (currently only 'count' is supported)", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of user labels", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "labels": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Label identifier" + }, + "private": { + "type": "boolean", + "description": "Whether this label is private" + }, + "label": { + "type": "string", + "description": "Label name" + }, + "count": { + "type": "integer", + "description": "Number of VNs with this label" + } + }, + "required": ["id", "private", "label"] + } + } + }, + "required": ["labels"] + } + } + } + }, + "400": { + "description": "Invalid request" + } + } + } + }, + "/ulist/{id}": { + "patch": { + "tags": ["List Management"], + "summary": "Update a visual novel in user's list", + "description": "Add or update a visual novel in the user's list", + "operationId": "updateUserListItem", + "security": [ + { + "tokenAuth": ["listwrite"] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Visual novel ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "vote": { + "type": ["integer", "null"], + "description": "Vote between 10 and 100", + "minimum": 10, + "maximum": 100 + }, + "notes": { + "type": ["string", "null"], + "description": "User notes" + }, + "started": { + "type": ["string", "null"], + "description": "Start date (YYYY-MM-DD)" + }, + "finished": { + "type": ["string", "null"], + "description": "Finish date (YYYY-MM-DD)" + }, + "labels": { + "type": "array", + "description": "Label IDs to set (replaces existing labels)", + "items": { + "type": "integer" + } + }, + "labels_set": { + "type": "array", + "description": "Label IDs to add (does not affect existing labels)", + "items": { + "type": "integer" + } + }, + "labels_unset": { + "type": "array", + "description": "Label IDs to remove", + "items": { + "type": "integer" + } + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Successfully updated" + }, + "400": { + "description": "Invalid request" + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Insufficient permissions" + } + } + }, + "delete": { + "tags": ["List Management"], + "summary": "Remove a visual novel from user's list", + "description": "Remove a visual novel and its associated releases from the user's list", + "operationId": "deleteUserListItem", + "security": [ + { + "tokenAuth": ["listwrite"] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Visual novel ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Successfully removed" + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Insufficient permissions" + } + } + } + }, + "/rlist/{id}": { + "patch": { + "tags": ["List Management"], + "summary": "Update a release in user's list", + "description": "Add or update a release in the user's list", + "operationId": "updateReleaseListItem", + "security": [ + { + "tokenAuth": ["listwrite"] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Release ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "Release status (0=Unknown, 1=Pending, 2=Obtained, 3=On loan, 4=Deleted)", + "minimum": 0, + "maximum": 4 + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Successfully updated" + }, + "400": { + "description": "Invalid request" + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Insufficient permissions" + } + } + }, + "delete": { + "tags": ["List Management"], + "summary": "Remove a release from user's list", + "description": "Remove a release from the user's list", + "operationId": "deleteReleaseListItem", + "security": [ + { + "tokenAuth": ["listwrite"] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Release ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Successfully removed" + }, + "401": { + "description": "Authentication required" + }, + "403": { + "description": "Insufficient permissions" + } + } + } + } + }, + "components": { + "schemas": { + "QueryRequest": { + "type": "object", + "properties": { + "filters": { + "description": "Filters to determine which database items to fetch", + "oneOf": [ + { + "type": "array" + }, + { + "type": "string" + } + ] + }, + "fields": { + "type": "string", + "description": "Comma-separated list of fields to fetch for each database item" + }, + "sort": { + "type": "string", + "description": "Field to sort on" + }, + "reverse": { + "type": "boolean", + "description": "Sort in descending order", + "default": false + }, + "results": { + "type": "integer", + "description": "Number of results per page (max 100)", + "default": 10, + "maximum": 100, + "minimum": 0 + }, + "page": { + "type": "integer", + "description": "Page number (starting from 1)", + "default": 1, + "minimum": 1 + }, + "user": { + "type": ["string", "null"], + "description": "User ID to filter by" + }, + "count": { + "type": "boolean", + "description": "Include total count in response", + "default": false + }, + "compact_filters": { + "type": "boolean", + "description": "Include compact filter representation in response", + "default": false + }, + "normalized_filters": { + "type": "boolean", + "description": "Include normalized filter representation in response", + "default": false + } + } + }, + "QueryResponse": { + "type": "object", + "properties": { + "results": { + "type": "array", + "description": "Array of objects representing the query results", + "items": { + "type": "object" + } + }, + "more": { + "type": "boolean", + "description": "Whether more results are available on the next page" + }, + "count": { + "type": "integer", + "description": "Total number of entries matching the filters" + }, + "compact_filters": { + "type": "string", + "description": "Compact string representation of the filters" + }, + "normalized_filters": { + "type": "array", + "description": "Normalized JSON representation of the filters" + } + }, + "required": ["results", "more"] + } + }, + "securitySchemes": { + "tokenAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "Token", + "description": "API token obtained from the VNDB website (https://vndb.org/u/tokens)" + } + } + } +} \ No newline at end of file