{
  "openapi": "3.1.0",
  "info": {
    "title": "The Big MMORPG List API",
    "version": "1.0.0",
    "summary": "Read-only data for the MMO / MMORPG game directory.",
    "description": "Free, read-only JSON access to the games, categories and news on The Big MMORPG List. No authentication. Please cite the game's `url` when you use this data.",
    "contact": { "name": "The Big MMORPG List", "url": "https://thebigmmorpglist.com/contact-us/" },
    "termsOfService": "https://thebigmmorpglist.com/terms-of-use/"
  },
  "servers": [{ "url": "https://thebigmmorpglist.com" }],
  "paths": {
    "/api/games/": {
      "get": {
        "operationId": "listGames",
        "summary": "List and filter games",
        "description": "Games sorted A-Z. Combine filters to narrow the list, e.g. Free to Play 3D MMORPGs: ?type=MMORPG&graphics=3D&retail=Free&subscription=Free",
        "parameters": [
          { "name": "q", "in": "query", "description": "Text contained in the game title.", "schema": { "type": "string" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["MMORPG", "MMOFPS", "Battle Royale", "MMO Sport", "MMO Strategy", "MOBA", "Extraction Shooter", "Social"] } },
          { "name": "graphics", "in": "query", "schema": { "type": "string", "enum": ["2D", "3D"] } },
          { "name": "pov", "in": "query", "description": "Point of view.", "schema": { "type": "string", "enum": ["Third Person", "First Person", "Side-scrolling"] } },
          { "name": "platform", "in": "query", "schema": { "type": "string", "enum": ["Client Based", "Browser Based", "Mobile", "Both"] } },
          { "name": "retail", "in": "query", "description": "Whether the game must be bought.", "schema": { "type": "string", "enum": ["Free", "Cost"] } },
          { "name": "subscription", "in": "query", "description": "Free = no subscription (Free to Play with retail=Free, Buy to Play with retail=Cost), Pay = Pay to Play, Premium = no subscription required with an optional membership.", "schema": { "type": "string", "enum": ["Free", "Pay", "Premium"] } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }
        ],
        "responses": {
          "200": {
            "description": "A page of games.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GameList" } } }
          }
        }
      }
    },
    "/api/games/{slug}/": {
      "get": {
        "operationId": "getGame",
        "summary": "Get one game",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "description": "The game's slug, e.g. apex-legends.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "The game.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GameDetail" } } } } }
          },
          "404": { "description": "No game with that slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/categories/": {
      "get": {
        "operationId": "listCategories",
        "summary": "List categories with game counts",
        "responses": {
          "200": {
            "description": "All categories.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } }
          }
        }
      }
    },
    "/api/news/": {
      "get": {
        "operationId": "listNews",
        "summary": "Latest MMO news articles",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }
        ],
        "responses": {
          "200": {
            "description": "Newest articles first.",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } } } } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Rating": {
        "type": ["object", "null"],
        "description": "Average of registered users' 1-5 star reviews; null when unrated.",
        "properties": {
          "average": { "type": "number" },
          "count": { "type": "integer" },
          "best": { "type": "integer" },
          "worst": { "type": "integer" }
        }
      },
      "GameSummary": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "url": { "type": "string", "format": "uri", "description": "Canonical page to cite." },
          "api_url": { "type": "string", "format": "uri" },
          "image": { "type": "string", "format": "uri" },
          "type": { "type": "string" },
          "graphics": { "type": "string" },
          "setting": { "type": ["string", "null"] },
          "point_of_view": { "type": "string" },
          "platform": { "type": "string" },
          "retail": { "type": "string" },
          "subscription": { "type": "string" },
          "rating": { "$ref": "#/components/schemas/Rating" }
        }
      },
      "Specs": {
        "type": ["object", "null"],
        "properties": {
          "OS": { "type": "string" },
          "CPU": { "type": "string" },
          "RAM": { "type": "string" },
          "GPU": { "type": "string" },
          "Storage": { "type": "string" },
          "Network": { "type": "string" }
        }
      },
      "GameDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/GameSummary" },
          {
            "type": "object",
            "properties": {
              "developer": { "type": ["string", "null"] },
              "publisher": { "type": ["string", "null"] },
              "released": { "type": ["string", "null"] },
              "official_site": { "type": ["string", "null"], "format": "uri" },
              "description": { "type": "string" },
              "system_requirements": {
                "type": "object",
                "properties": {
                  "minimum": { "$ref": "#/components/schemas/Specs" },
                  "recommended": { "$ref": "#/components/schemas/Specs" }
                }
              },
              "updated": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "GameList": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/GameSummary" } },
          "meta": {
            "type": "object",
            "properties": {
              "page": { "type": "integer" },
              "per_page": { "type": "integer" },
              "total": { "type": "integer" },
              "total_pages": { "type": "integer" }
            }
          },
          "links": {
            "type": "object",
            "properties": {
              "self": { "type": "string", "format": "uri" },
              "next": { "type": ["string", "null"], "format": "uri" },
              "prev": { "type": ["string", "null"], "format": "uri" }
            }
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "games": { "type": "integer" }
        }
      },
      "Article": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "game": { "type": "string" },
          "published": { "type": "string", "format": "date-time" },
          "image": { "type": "string", "format": "uri" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      }
    }
  }
}