JSON-DB-Core_FDR.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "moral-tuning",
   "metadata": {},
   "source": [
    "# Henry Morgenthau Jr. Diary Index\n",
    "\n",
    "## API\n",
    "\n",
    "The API uses graphql, so there is only one endpoint: <https://hmjrapi-prod.herokuapp.com>\n",
    "\n",
    "interface EntriesInput {\n",
    "  max: number // The upper limit of entries to return\n",
    "  keywords: string[] // An array of strings, at least one of which must be present in the returning entries\n",
    "  dates: Date[] // An array of dates, which must be included in the returned entries\n",
    "  books: string[] // An array of books from which entries can be returned\n",
    "}\n",
    "\n",
    "The date object mentioned previously looks like this:\n",
    "\n",
    "inteface DateInput {\n",
    "  day: number // Two digits, 1 - 31 for the day\n",
    "  month: number // Two digits, 1 - 12 for the month\n",
    "  year: number // Two digits corresponding to a year in the 20th century, ie 43 -> 1943\n",
    "}\n",
    "\n",
    "GraphQL stands for graph query language - so querying this API requires learning a bit of a new language.\n",
    "\n",
    "To query, send a POST request to the endpoint with a JSON body that looks like this:\n",
    "\n",
    "{\n",
    "  query: foo // GQL query string here\n",
    "  variables: bar // An object containing values for variables referenced in your query string.\n",
    "}\n",
    "\n",
    "In python, defining a query string might look like this:\n",
    "\n",
    "\"\"\"\n",
    "query ($max: Float!, $keywords: [String!]!, $dates: [DateInput!]!, $books: [String!]!) {\n",
    "                entries(max: $max, keywords: $keywords, dates: $dates, books:$books) {\n",
    "                    header\n",
    "                    content\n",
    "                }\n",
    "            }\n",
    "\"\"\"\n",
    "\n",
    "This query string is written in GQL, and vaguely resembles a function call. Words prefixed with a $ are variables. That variable object should look like this:\n",
    "\n",
    "{\n",
    "  max: 5,\n",
    "  keywords: [\"refugee\"],\n",
    "  dates: [],\n",
    "  books: []\n",
    "}\n",
    "\n",
    "The values of this object are just examples, although keywords, dates and books must be arrays (even if empty).\n",
    "\n",
    "The server will respond with an array of entries fitting the query.\n",
    "\n",
    "interface Entry {\n",
    "  book: string,\n",
    "  header: string,\n",
    "  content: string,\n",
    "  dates: Date[],\n",
    "  indexes: Index[]\n",
    "}\n",
    "\n",
    "interface Date {\n",
    "  day: number,\n",
    "  month: number, \n",
    "  year: number, // Two digit year again, ie 43 -> 1943\n",
    "  content: string, // The content of the entry this date is associated with\n",
    "}\n",
    "\n",
    "interface Index {\n",
    "  book: string, // The volume this index refers to\n",
    "  page: number, // The page in the volume\n",
    "  content: string // The content of the entry this index is associated with\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "operating-while",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}