swagger.json

{
  "openapi": "3.0.0",
  "info": {
    "description": "banidb-api docs",
    "version": "1",
    "title": "banidb-api"
  },
  "servers": [
    {
      "url": "",
      "description": "live endpoint"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Make sure api is up and running",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/search/{query}": {
      "get": {
        "summary": "Search",
        "description": "Enter a search query and get lines that match.",
        "parameters": [
          {
            "name": "query",
            "in": "path",
            "description": "Search query",
            "required": true,
            "type": "string"
          },
          {
            "name": "searchtype",
            "in": "query",
            "description": "Type of search. { 0: First letter each word from start (Gurmukhi), 1: First letter each word anywhere (Gurmukhi), 2: Full Word (Gurmukhi), 3: Full Word Translation (English), 4: Romanized Gurmukhi (English), 5: Ang, 6: Main Letter (Gurmukhi), 7: Romanized first letter anywhere (English) }",
            "required": false,
            "schema": {
              "$ref": "#/definitions/SearchType"
            }
          },
          {
            "name": "source",
            "in": "query",
            "description": "Source to search in. { G: Guru Granth Sahib Ji, D: Dasam Granth Sahib, B: Bhai Gurdas Ji Vaaran, A: Amrit Keertan, S: Bhai Gurdas Singh Ji Vaaran, N: Bhai Nand Lal Ji Vaaran, R: Rehatnamas & Panthic Sources, all: All sources }",
            "required": false,
            "schema": {
              "$ref": "#/definitions/Source"
            }
          },
          {
            "name": "ang",
            "in": "query",
            "description": "Which ang to return. Required if searchtype is 5",
            "required": false,
            "type": "number"
          },
          {
            "name": "raag",
            "in": "query",
            "description": "Which raag to limit search to.",
            "required": false,
            "type": "number"
          },
          {
            "name": "writer",
            "in": "query",
            "description": "Which writer to limit search to.",
            "required": false,
            "type": "number"
          },
          {
            "name": "page",
            "in": "query",
            "description": "Pagination param. Which results page to return",
            "required": false,
            "type": "number"
          },
          {
            "name": "results",
            "in": "query",
            "description": "Pagination param. How many results per page to return.",
            "required": false,
            "type": "number"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/shabads/{shabadID}": {
      "get": {
        "summary": "Shabads by ID",
        "description": "Get an entire Shabad from its shabadID. More than one shabadID can be specificed with operators '+' or ','",
        "parameters": [
          {
            "name": "shabadID",
            "in": "path",
            "description": "Shabad id(s)",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          },
          "400": {
            "description": "Malformed URL"
          }
        }
      }
    },
    "/angs/{pageNo}/{sourceID}": {
      "get": {
        "summary": "Ang",
        "description": "Get an entire Ang(s) by number and optional source. More than one Ang can be specificed with operators '+' and '-'",
        "parameters": [
          {
            "name": "pageNo",
            "in": "path",
            "description": "Ang number or range(s). Examples: '1', '2-3', '4+6', '2-3+7', '1-4+7-9' ",
            "required": true,
            "type": "string"
          },
          {
            "name": "sourceID",
            "in": "path",
            "description": "Source to search in. Defaults of G when omitted. { G: Guru Granth Sahib Ji, D: Dasam Granth Sahib, B: Bhai Gurdas Ji Vaaran, A: Amrit Keertan, S: Bhai Gurdas Singh Ji Vaaran N: Bhai Nand Lal Ji Vaaran, R: Rehatnamas & Panthic Sources }",
            "required": false,
            "schema": {
              "$ref": "#/definitions/AngSources"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          },
          "400": {
            "description": "Malformed URL"
          }
        }
      }
    },
    "/hukamnamas/{year}/{month}/{day}": {
      "get": {
        "summary": "Hukamnama",
        "description": "Get the Hukamnama from Sri Harmandir Sahib.",
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "description": "Year for specific date of Hukamnama. Required if month and day are specified.",
            "required": false,
            "type": "string"
          },
          {
            "name": "month",
            "in": "path",
            "description": "Month for specific date of Hukamnama. Required if year and day are specified.",
            "required": false,
            "type": "string"
          },
          {
            "name": "day",
            "in": "path",
            "description": "Day for specific date of Hukamnama. Required if year and month are specified.",
            "required": false,
            "type": "string"
          }
        ]
      },
      "responses": {
        "200": {
          "description": "successful operation"
        },
        "404": {
          "description": "Please specify a valid date. Archives go back to 2002-01-01"
        }
      }
    },
    "/random/{sourceID}": {
      "get": {
        "summary": "Retrieve a random Shabad",
        "description": "Get Randomly selected  Shabad.",
        "parameters": [
          {
            "name": "sourceID",
            "in": "path",
            "description": "Source to search in. Defaults of G when omitted. { G: Guru Granth Sahib Ji, D: Dasam Granth Sahib, B: Bhai Gurdas Ji Vaaran, A: Amrit Keertan, S: Bhai Gurdas Singh Ji Vaaran, N: Bhai Nand Lal Ji Vaaran, R: Rehatnamas & Panthic Sources, all: All sources }",
            "required": false,
            "schema": {
              "$ref": "#/definitions/Source"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          },
          "400": {
            "description": "Malformed URL"
          }
        }
      }
    },
    "/banis": {
      "get": {
        "summary": "Banis List",
        "description": "Get a list of banis found in sundar gutka.",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/banis/{baniID}": {
      "get": {
        "summary": "Bani",
        "description": "Get a specific bani found in sundar gutka by baniID.",
        "parameters": [
          {
            "name": "baniID",
            "in": "path",
            "description": "Bani ID",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/amritkeertan": {
      "get": {
        "summary": "Amrit Keertan List",
        "description": "Get a list of all headers found in Amrit Keertan.",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/amritkeertan/index": {
      "get": {
        "summary": "Amrit Keertan List",
        "description": "Get a list of all indexes found in Amrit Keertan.",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/amritkeertan/index/{headerID}": {
      "get": {
        "summary": "Amrit Keertan List",
        "description": "Get a list of all indexes found in Amrit Keertan for a specific header.",
        "parameters": [
          {
            "name": "headerID",
            "in": "path",
            "description": "Header id",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/amritkeertan/shabads/{shabadID}": {
      "get": {
        "summary": "Amrit Keertan List",
        "description": "Get shabads found in Amrit Keertan by number",
        "parameters": [
          {
            "name": "shabadID",
            "in": "path",
            "description": "Shabad id",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/kosh/{letter}": {
      "get": {
        "summary": "Kosh letter",
        "description": "Get words in kosh table by letter.",
        "parameters": [
          {
            "name": "letter",
            "in": "path",
            "description": "letter",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/kosh/word/{word}": {
      "get": {
        "summary": "Kosh word",
        "description": "Get words in kosh table by word.",
        "parameters": [
          {
            "name": "word",
            "in": "path",
            "description": "word to partial match",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/kosh/search/{query}": {
      "get": {
        "summary": "Kosh Search",
        "description": "Get words in kosh table by query.",
        "parameters": [
          {
            "name": "query",
            "in": "path",
            "description": "query to search on",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/rehats": {
      "get": {
        "summary": "Rehat Maryadas list",
        "description": "Get a list of rehat maryads that are provided by BaniDB.",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/rehats/{rehatID}": {
      "get": {
        "summary": "Rehat Maryada chapters",
        "description": "Get the chapters for a specific rehat maryada found in by rehatID.",
        "parameters": [
          {
            "name": "rehatID",
            "in": "path",
            "description": "Rehat ID",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/rehats/{rehatID}/chapters/{chapterID}": {
      "get": {
        "summary": "Rehat Maryada chapter contents",
        "description": "Get the chapter contents for a specific chapter by chapterID of a specific rehat maryada found by rehatID.",
        "parameters": [
          {
            "name": "rehatID",
            "in": "path",
            "description": "Rehat ID",
            "required": true,
            "type": "string"
          },
          {
            "name": "chapterID",
            "in": "path",
            "description": "Chapter ID",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/rehats/search/{query}": {
      "get": {
        "summary": "Rehat Maryada search",
        "description": "Enter a search query and get chapters from rehats that match.",
        "parameters": [
          {
            "name": "query",
            "in": "path",
            "description": "Query string",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/writers": {
      "get": {
        "summary": "Writers meta-data",
        "description": "Get writers available to be used for search endpoint.",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/raags": {
      "get": {
        "summary": "Raags meta-data",
        "description": "Get raags available to be used for search endpoint.",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    },
    "/sources": {
      "get": {
        "summary": "Sources meta-data",
        "description": "Get sources available to be used for search endpoint.",
        "responses": {
          "200": {
            "description": "successful operation"
          }
        }
      }
    }
  },
  "definitions": {
    "SearchType": {
      "type": "number",
      "enum": [0, 1, 2, 3, 4, 5, 6, 7]
    },
    "AngSources": {
      "type": "string",
      "enum": ["G", "D", "B", "A", "S", "N", "R"]
    },
    "Source": {
      "type": "string",
      "enum": ["G", "D", "B", "A", "S", "N", "R", "all"]
    },
    "Sabad": {
      "type": "object",
      "properties": {
        "shabadInfo": {
          "type": "string"
        }
      }
    }
  }
}