Chapitre 13 - Créer une API.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Chapitre 12 - Créer une API\n",
    "===\n",
    "\n",
    "## A ? P ? I ?\n",
    "\n",
    "### Quoi ?\n",
    "\n",
    "Une API (Application Programming Interface) est un système informatique prévu pour la communication de données ou de fonctions à des services tiers. L'équipe de développement prévoit ainsi un moyen externe de réaliser des transactions depuis l'extérieur sans avoir à accéder au code interne d'un projet ou à ses données au format brut.\n",
    "\n",
    "Les exemples d'API sont nombreux et touchent aussi bien le Web que le logiciel et les librairies de développement. Pour donner un exemple, on trouve des APIs servant des données (IIIF et les métadonnées d'image par exemple, OAI PMH et les métadonnées de catalogue, etc.) ou bien même des fonctions telles que Google Translate ([Documentation](https://cloud.google.com/translate/docs/quickstart)) ou d'autres telles que [LemLat](http://cophilab.ilc.cnr.it:8080/LatMorphWebApp/services/complete/arma,cano,domus) qui fournit l'analyse morphologique de mots latins.\n",
    "\n",
    "Cependant, toutes les APIs ne sont pas forcément produites pour leur consommation par des tiers. Dans beaucoup de cas, il sera intéressant pour un projet de pouvoir fournir un moyen de communication entre le client et le serveur une fois les données chargées. \n",
    "\n",
    "![Autocomplete](images/autocomplete.gif)\n",
    "\n",
    "\n",
    "Un exemple très commun serait l'*autocomplétion* d'un formulaire de recherche. Quand l'utilisateur tape quelques lettres, un script du côté client ira communiquer avec une page de l'API pour récupérer les données sans rafraichir la page actuelle."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Comment ?\n",
    "\n",
    "La consommation de données est bien évidemment le point le plus complexe d'une API: on voudra s'arranger un maximum pour que les données fournies soit faciles à extraire. Prenons deux exemples : une page HTML et un fichier JSON qui contiennent les mêmes données.\n",
    "\n",
    "![Requête sur une version en HTML](./images/latin.html.png)\n",
    "\n",
    "L'XPath correspondant à la deuxième traduction de `cano` est : `/html/body/div[1]/div/section/div/div[2]/ul[3]/li[2]`. On peut boucler sur `/html/body/div[1]/div/section/div/div[2]/ul` puis sur les `li` mais il est impossible, sans expression régulière, de diviser les traductions des analyses.\n",
    "\n",
    "![Requête sur une version en JSON](./images/latin.json.png)\n",
    "\n",
    "Le chemin JSON correspondant est `[\"results\"][2]` où l'on trouve les analyses en dans une liste telle que `[\"results\"][2][\"analysis\"][0][\"lemmas\"][0][\"lemma\"]` est égal à `cano`. Il est aussi très facile de boucler dessus.\n",
    "\n",
    "| Élément de comparaison | HTML   | JSON   |\n",
    "| ----------------------- | ------ | ------ |\n",
    "| Poids                   | 7364 o | 5257 o (mais avec plus d'informations propres à la requête) |\n",
    "| Parsage                 | Capable d'échouer si une page web est mal construire dans son header | Très peu probable d'échouer |\n",
    "| Disponibilités dans les langages | Moyenne (librairies externes souvent) | Élevée |\n",
    "\n",
    "Il va s'en dire que, d'abord pour le poids et la facilité de lecture machine, **le JSON est le plus abordable**. Il existe d'autres formats acceptable (XML par exemple) mais pour toute donnée structurée autre que du texte balisé, il est recommandé de passer par du JSON (sur ce point : *[Mobile Performance testing JSON vs XML (2016)](https://www.infragistics.com/community/blogs/b/torrey-betts/posts/mobile-performance-testing-json-vs-xml), [JSON vs XML: A Comparative Performance Analysis  of Data Exchange Formats](http://ijcsn.org/IJCSN-2014/3-4/JSON-vs-XML-A-Comparative-Performance-Analysis-of-Data-Exchange-Formats.pdf), [JSON ou XML, quel format choisir? ](https://www.scriptol.fr/ajax/json-xml.php)*)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Le gazetteer en données ouvertes\n",
    "\n",
    "Nous allons chercher à partager nos données directement avec les utilisateurs. Nous allons prévoir deux visualisations des données : une page de recherche et une page pour un objet particulier.\n",
    "\n",
    "### jsonify \n",
    "\n",
    "#### Flask et les Response\n",
    "\n",
    "Votre premier réflexe sera surement d'utiliser **`json.dumps()`**. Cela montre que vous avez compris le cours. Cependant... **cela ne sera pas suffisant.**\n",
    "\n",
    "Rappelez-vous, sur le web, une réponse est basée sur trois paramètres :\n",
    "- les headers\n",
    "- le code http\n",
    "- le corps\n",
    "\n",
    "Or, si l'on fait `return json.dumps()` nous ne retournons qu'une chaine de caractères... Mais alors, que faisait `render_template` me demanderez-vous ?\n",
    "\n",
    "En fait, `render_template()` ne renvoit pas une chaine de caractère (c'était prévisible...) mais un objet `Response` qui est constitué d'un corps, d'un code http et d'un headers. Et vu que vous envoyez un template en html, la réponse dit \"bon, le code par défaut, c'est *200* et les headers, on va prévenir que le mimetype du corps est *html*\".\n",
    "\n",
    "Et de fait, Flask, pour fonctionner véritablement correctement, a besoin de `Reponse`. Une [`Response`](http://flask.pocoo.org/docs/0.12/api/#response-objects) a 2 paramètres qui nous importent:\n",
    "- `.headers` qui se comporte comme un dictionnaire\n",
    "- `.status_code` qui se comportent comme un entier\n",
    "\n",
    "de telle manière que l'on peut écrire :\n",
    "\n",
    "```python\n",
    "from flask import Flask, Response\n",
    "\n",
    "app = Flask(\"Nom\")\n",
    "\n",
    "@app.route(\"/404\")\n",
    "def erreur_404():\n",
    "    response = Response(\"Il y a eu une erreur\")\n",
    "    response.headers[\"content-type\"] = \"text/plain\"\n",
    "    response.status_code = 404\n",
    "    return response\n",
    "```\n",
    "\n",
    "ou bien encore\n",
    "\n",
    "```python\n",
    "from flask import Flask, Response\n",
    "import json\n",
    "app = Flask(\"Nom\")\n",
    "\n",
    "@app.route(\"/du_json\")\n",
    "def une_route():\n",
    "    mon_dictionnaire = {\"une_cle\" : \"une valeur\"}\n",
    "    mon_json = json.dumps(mon_dictionnaire)\n",
    "    # Juste une autre manière d'écrire ce qui a été écrit au-dessus\n",
    "    response = Response(mon_json, status=200, mimetype=\"application/json\")\n",
    "    return response\n",
    "```\n",
    "\n",
    "#### La méthode rapide\n",
    "\n",
    "Tout développeur-se étant un-e fainéant-e intelligent-e (ou inversement), l'équipe derrière Flask a ajouté une fonction un peu raccourcie pour le même résultat que le dernier exemple : `flask.jsonify()` :\n",
    "\n",
    "```python\n",
    "from flask import Flask, jsonify\n",
    "import json\n",
    "app = Flask(\"Nom\")\n",
    "\n",
    "@app.route(\"/du_json\")\n",
    "def une_route():\n",
    "    mon_dictionnaire = {\"une_cle\" : \"une valeur\"}\n",
    "    return jsonify(mon_dictionnaire)\n",
    "```\n",
    "\n",
    "et vu que jsonify retourne une `Response`, on peut aussi changer le code d'erreur :\n",
    "\n",
    "```python\n",
    "from flask import Flask, jsonify\n",
    "import json\n",
    "app = Flask(\"Nom\")\n",
    "\n",
    "@app.route(\"/erreur404\")\n",
    "def une_route():\n",
    "    mon_dictionnaire = {\"message\" : \"Vous avez une belle erreur ici !\"}\n",
    "    response = jsonify(mon_dictionnaire)\n",
    "    response.status_code = 404\n",
    "    return response\n",
    "```\n",
    "\n",
    "Plutôt simple non ?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tout n'est pas `jsonifiable` de base....\n",
    "\n",
    "Nous avons vu jusque là qu'il était facile de convertir dictionnaires, listes, booléens, nombres, `None` et autres types très simples de Python. Qu'en est-il des données plus complexes telles que nous avons récupéré de notre base de données ?\n",
    "\n",
    "`jsonify` étant basé sur `json.dumps()`, nous pouvons essayer `json.dumps()` sur nos objets :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from modules_cours.gazetteer.modeles.donnees import Place\n",
    "from modules_cours.gazetteer.app import app\n",
    "from json import dumps\n",
    "\n",
    "data = Place.query.get(1)\n",
    "print(data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "dumps(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`TypeError: <Place 1> is not JSON serializable` est normalement le retour final. `dump` et `dumps` ne savent pas gérer les objets que vous créez vous-mêmes. Comment faire alors ?\n",
    "\n",
    "**La solution est simple:** on prévoit une fonction qui transformera nos objets en dictionnaires, liste, etc. Par exemple :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def place_to_json(place):\n",
    "    return {\n",
    "        \"nom\": place.place_nom,\n",
    "        \"description\": place.place_description,\n",
    "        \"longitude\": place.place_longitude,\n",
    "        \"latitude\": place.place_latitude\n",
    "    }\n",
    "\n",
    "print(dumps(place_to_json(data)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ultimement, on s'arrangera pour que la fonction soit facilement accessible en la transformant en méthode : \n",
    "\n",
    "```python\n",
    "class Place(db.Model):\n",
    "    place_id = db.Column(db.Integer, unique=True, nullable=False, primary_key=True, autoincrement=True)\n",
    "    place_nom = db.Column(db.Text)\n",
    "    place_description = db.Column(db.Text)\n",
    "    place_longitude = db.Column(db.Float)\n",
    "    place_latitude = db.Column(db.Float)\n",
    "    place_type = db.Column(db.String(45))\n",
    "    \n",
    "    def to_dict(self):\n",
    "        return {\n",
    "            \"nom\": self.place_nom,\n",
    "            \"description\": self.place_description,\n",
    "            \"longitude\": self.place_longitude,\n",
    "            \"latitude\": self.place_latitude\n",
    "        }\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### La page de recherche en JSON\n",
    "\n",
    "Pour prévoir plus tard la capacité de créer un script pour faire de l'autocomplétion, nous allons proposer une route d'API permettant de faire une recherche plein texte.\n",
    "\n",
    "Le code va être très proche du code de recherche original, simplement nous allons :\n",
    "- proposer la navigation dans le json\n",
    "- proposer le lien vers le résultat dans le Json\n",
    "\n",
    "Pour gérer les différentes routes, nous avons divisé `routes.py` en `routes/general.py` et `routes/api.py`.\n",
    "\n",
    "#### api.py\n",
    "\n",
    "##### urllib\n",
    "\n",
    "URLLib est un package python bien agréable quand il s'agit de travailler sur des URLs. Nous utilisons ici `urllib.parse.urlencode` afin d'encoder des paramètres `GET` via un dictionnaire. On pensera à ajouter `?` devant.\n",
    "\n",
    "##### url_for(..., _external=True)\n",
    "\n",
    "Le paramètre `_external=True` de `url_for()` permet de générer une URL absolue et non simplement une URL relative.\n",
    "\n",
    "\n",
    "```python\n",
    "from flask import render_template, request, url_for, jsonify\n",
    "from urllib.parse import urlencode\n",
    "\n",
    "from ..app import app\n",
    "from ..constantes import LIEUX_PAR_PAGE, API_ROUTE\n",
    "from ..modeles.donnees import Place\n",
    "\n",
    "@app.route(API_ROUTE+\"/places\")\n",
    "def api_places_browse():\n",
    "    \"\"\" Route permettant la recherche plein-texte et la navigation classique\n",
    "\n",
    "    On s'inspirera de http://jsonapi.org/ faute de pouvoir trouver temps d'y coller à 100%\n",
    "    \"\"\"\n",
    "    # q est très souvent utilisé pour indiquer une capacité de recherche\n",
    "    motclef = request.args.get(\"q\", None)\n",
    "    page = request.args.get(\"page\", 1)\n",
    "\n",
    "    if isinstance(page, str) and page.isdigit():\n",
    "        page = int(page)\n",
    "    else:\n",
    "        page = 1\n",
    "\n",
    "    if motclef:\n",
    "        query = Place.query.filter(\n",
    "            Place.place_nom.like(\"%{}%\".format(motclef))\n",
    "        )\n",
    "    else:\n",
    "        query = Place.query\n",
    "\n",
    "    try:\n",
    "        resultats = query.paginate(page=page, per_page=LIEUX_PAR_PAGE)\n",
    "    except Exception:\n",
    "        return Json_404()\n",
    "\n",
    "    dict_resultats = {\n",
    "        \"links\": {\n",
    "            \"self\": request.url\n",
    "        },\n",
    "        \"data\": [\n",
    "            place.to_jsonapi_dict()\n",
    "            for place in resultats.items\n",
    "        ]\n",
    "    }\n",
    "\n",
    "    if resultats.has_next:\n",
    "        arguments = {\n",
    "            \"page\": resultats.next_num\n",
    "        }\n",
    "        if motclef:\n",
    "            arguments[\"q\"] = motclef\n",
    "        dict_resultats[\"links\"][\"next\"] = url_for(\"api_places_browse\", _external=True)+\"?\"+urlencode(arguments)\n",
    "\n",
    "    if resultats.has_prev:\n",
    "        arguments = {\n",
    "            \"page\": resultats.prev_num\n",
    "        }\n",
    "        if motclef:\n",
    "            arguments[\"q\"] = motclef\n",
    "        dict_resultats[\"links\"][\"prev\"] = url_for(\"api_places_browse\", _external=True)+\"?\"+urlencode(arguments)\n",
    "\n",
    "    response = jsonify(dict_resultats)\n",
    "    return response\n",
    "```\n",
    "\n",
    "#### Donnees.py\n",
    "\n",
    "```python\n",
    "from flask import url_for\n",
    "\n",
    "class Place(db.Model):\n",
    "    # ...\n",
    "\n",
    "    def to_jsonapi_dict(self):\n",
    "        \"\"\" It ressembles a little JSON API format but it is not completely compatible\n",
    "\n",
    "        :return:\n",
    "        \"\"\"\n",
    "        return {\n",
    "            \"type\": \"place\",\n",
    "            \"id\": self.place_id,\n",
    "            \"attributes\": {\n",
    "                \"name\": self.place_nom,\n",
    "                \"description\": self.place_description,\n",
    "                \"longitude\": self.place_longitude,\n",
    "                \"latitude\": self.place_latitude,\n",
    "                \"category\": self.place_type\n",
    "            },\n",
    "            \"links\": {\n",
    "                \"self\": url_for(\"lieu\", place_id=self.place_id, _external=True),\n",
    "                \"json\": url_for(\"api_places_single\", place_id=self.place_id, _external=True)\n",
    "            },\n",
    "            \"relationships\": {\n",
    "                 \"editions\": [\n",
    "                     author.author_to_json()\n",
    "                     for author in self.authorships\n",
    "                 ]\n",
    "            }\n",
    "        }\n",
    "```\n",
    "\n",
    "Codes issus de :\n",
    "- [cours-flask/exemple17/gazetteer/modeles/donnees.py](cours-flask/exemple17/gazetteer/modeles/donnees.py)\n",
    "- [cours-flask/exemple17/gazetteer/routes/api.py](cours-flask/exemple17/gazetteer/routes/api.py) \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### L'affichage en GEOJson\n",
    "\n",
    "À partir de la documentation donnée ci-après, corriger le code suivant afin de fournir une vue en GeoJson :\n",
    "\n",
    "(Dans exemple-17)\n",
    "```python\n",
    "@app.route(API_ROUTE+\"/places/<place_id>\")\n",
    "def api_places_single(place_id):\n",
    "    try:\n",
    "        query = Place.query.get(place_id)\n",
    "        return jsonify(query.to_jsonapi_dict())\n",
    "    except:\n",
    "        return Json_404()\n",
    "```\n",
    "\n",
    "- [GeoJson.org](http://geojson.org/)\n",
    "- [Wikipedia : GeoJson](https://en.wikipedia.org/wiki/GeoJSON)\n",
    "- [Exemple GeoJson Pleiades](https://pleiades.stoa.org/places/837078212/json)"
   ]
  }
 ],
 "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}