{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 1: API requests (WikiWho wrapper)\n",
    "\n",
    "The WikiWho class wraps the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/) and [WikiWho Edit Persistence API](https://www.wikiwho.net/en/edit_persistence/v1.0.0-beta/) requests into functions, through the `api` attribute (`WikiWhoAPI` class)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Create an instance of WikiWho\n",
    "\n",
    "The `api` attribute of the `WikiWho` class contains all the functions to call the APIs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from wikiwho_wrapper import WikiWho\n",
    "ww = WikiWho(lng='en')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Parameters of WikiWho\n",
    "\n",
    "- *wikiwho_api_username* (str, optional): WikiWho API username\n",
    "- *wikiwho_api_password* (str, optional): WikiWho API password\n",
    "- *wikiwho_api_key* (str, optional): WikiWho API key\n",
    "- *lng* (str, optional): the language that needs to be query\n",
    "- *protocol* (str, optional): the protocol of the url\n",
    "- *domain* (str, optional): the domain that hosts the api\n",
    "- *version* (str, optional): the version of the api\n",
    "- *attempts* (int, optional): the number of attempts before giving up trying to connect"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Querying all content\n",
    "\n",
    "The method `all_content()` corresponds to the following requests:\n",
    "\n",
    "    GET /all_content/{article_title}/ \n",
    "    GET /all_content/{article_id}/ \n",
    "    \n",
    "Internally, the method will discern by the two call depending on the type first parameter (`str` for `article_title` and `int` for `article_id`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ww.api.all_content(\"Bioglass_45S5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***You can also use all the parameters of the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/)***\n",
    "\n",
    "- *article* (Union[int, str]): page id (int) or title (str) of the page.\n",
    "- *o_rev_id* (bool, optional): Origin revision ID per token\n",
    "- *editor* (bool, optional): Editor ID/Name per token\n",
    "- *token_id* (bool, optional): Token ID per token\n",
    "- *out* (bool, optional): Outbound revision IDs per token\n",
    "- *_in* (bool, optional): Outbound revision IDs per token"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Query Revisions IDS\n",
    "\n",
    "The method `rev_ids_of_article()` corresponds to the following requests:\n",
    "\n",
    "    GET /rev_ids/{article_title}/\n",
    "    GET /rev_ids/page_id/{page_id}/\n",
    "    \n",
    "As in the previous case, ***You can also use all the parameters of the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/)***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ww.api.rev_ids_of_article(article='Bioglass_45S5')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Query the content of specific revisions\n",
    "\n",
    "In this case, there are three methods that match the 5 different requests:\n",
    "\n",
    "- `last_rev_content()`:\n",
    "\n",
    "        GET /rev_content/{article_title}/\n",
    "        GET /rev_content/page_id/{page_id}/\n",
    "    \n",
    "- `specific_rev_content_by_rev_id()`:\n",
    "    \n",
    "        GET /rev_content/{article_title}/{rev_id}/ \n",
    "        GET /rev_content/rev_id/{rev_id}\n",
    "\n",
    "- `range_rev_content_by_article_title()`:\n",
    "\n",
    "        GET /rev_content/{article_title}/{start_rev_id}/{end_rev_id}/ \n",
    "\n",
    "    \n",
    "As in the previous case, ***You can also use all the parameters of the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/)***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ww.api.range_rev_content_by_article_title(article='Bioglass_45S5',  start_rev_id=18064039,  end_rev_id=207995408)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Query the content of persistance of actions\n",
    "\n",
    "In this case, there is one method that match the 3 different requests:\n",
    "\n",
    "- `edit_persistence()`:\n",
    "\n",
    "        GET /editor/{editor_id}/\n",
    "        GET /page/{page_id}/\n",
    "        GET /page/editor/{page_id}/{editor_id}/\n",
    "\n",
    "As in the previous case, ***You can also use all the parameters of the [WikiWho Edit Persistence API](https://www.wikiwho.net/en/api_editor/v1.0.0-beta/)***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ww.api.edit_persistence(page_id=2161298)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Summary\n",
    "\n",
    "Although in the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/), there are 9 types of requests, the wrapper reduces it to 5 functions (3 to 1 in the case of the [WikiWho Edit Persistence API](https://www.wikiwho.net/en/edit_persistence/v1.0.0-beta/)) by exploting the fact that a lot of these requests only vary in the type of the paramater for the page, i.e. id(`int`) or title(`str`):\n",
    "\n",
    "Here is the complete list of functions fo the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/):\n",
    "\n",
    "- `all_content()`\n",
    "- `rev_ids_of_article()`\n",
    "- `last_rev_content()`\n",
    "- `specific_rev_content_by_rev_id()`\n",
    "- `range_rev_content_by_article_title()`\n",
    "\n",
    "And, for the [WikiWho Edit Persistence API](https://www.wikiwho.net/en/edit_persistence/v1.0.0-beta/), we only have one function\n",
    "\n",
    "- `edit_persistence()`\n",
    "\n",
    "Although, the JSON format of this request is useful for certain tasks that involves extracting detailed information, in many occasions you may prefer to work with a table representation of the date. The next part of the tutorial will show you that you can get the a pandas DataFrame instead, by using the DataView.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from utils.notebooks import get_next_notebook\n",
    "from IPython.display import HTML\n",
    "try:\n",
    "    display(HTML(f'<a href=\"{get_next_notebook()}\" target=\"_blank\">Go to next workbook</a>'))\n",
    "except:\n",
    "    HTML('<a href=\"2. Getting Dataframes (DataView).ipynb\" target=\"_blank\">Go to next workbook</a>')"
   ]
  }
 ],
 "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}