python-http.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# HTTP in Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "HTTP is een client-server protocol: de client, bijvoorbeeld de browser, stuurt een verzoek (*request*) naar de server,\n",
    "die een antwoord (*response*) terug stuurt.\n",
    "In ons geval is ons Python-programma (in dit notebook) de client. \n",
    "\n",
    "Met behulp van de `requests` library (https://requests.readthedocs.io) kun je in Python HTTP-verzoeken sturen\n",
    "en de antwoorden verwerken.\n",
    "Dit is de basis voor het gebruik van web-API's in Python.\n",
    "\n",
    "Voordat we de library kunnen gebruiken moeten we deze importeren:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Het eenvoudigste HTTP-*request* is `get`, met een URL als parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r = requests.get('https://ieni.org')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Aan de hand van de `status_code` kun je zien of de request geslaagd is, en een succesvolle response opgeleverd heeft.\n",
    "De waarde `200` geeft succes aan; `404` is een niet-gevonden pagina; enz."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r.status_code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "De *response* bevat onder meer de *headers* met metadata van de server."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for header in r.headers:\n",
    "    print(header)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "De `Content-type` header beschrijft het document-formaat van de response, in dit geval HTML:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r.headers['Content-Type']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We geven hier alleen een klein gedeelte van het ontvangen HTML-document weer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r.text[0:500]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Andere requests-mogelijkheden\n",
    "\n",
    "Met de `requests`-library kun je onder andere:\n",
    "\n",
    "* verzoeken versturen met verschillende HTTP-methods: naast `GET` ook `POST`, `PUT`, `DELETE`, enz.\n",
    "* authenticatie/autorisatiegegevens meegeven (username/password)\n",
    "* de headers die je opstuurt naar de server aanpassen\n",
    "* de parameters in de URL opgeven (`...?key1=value1&key=value...`)\n",
    "* de payload (data) opgeven voor een `POST` of `PUT`-request\n",
    "\n",
    "Hieronder en in de andere notebooks kom je een aantal van deze mogelijkheden tegen."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## JSON\n",
    "\n",
    "Zoals uit dit voorbeeld mogelijk blijkt, is HTML niet het meest handige formaat om in een programma te verwerken.\n",
    "De meeste web-API's gebruiken daarom het JSON-formaat (JavaScript Object Notation, zie https://json.org).\n",
    "JSON wordt veel gebruikt om \"objecten\" die je in programma's gebruikt buiten het programma te bewaren,\n",
    "bijvoorbeeld in een document-database (zoals MongoDB of CouchDB);\n",
    "en om objecten te communiceren naar andere programma's, zoals in web-API's.\n",
    "\n",
    "De JSON-notatie lijkt sterk op de Python Dictionary notatie.\n",
    "Voor het omzetten van een Python Dictionary naar en van JSON gebruiken we de functies `dumps` en `loads`: `string = json.dumps(object)` en `object = json.loads(string)`.\n",
    "\n",
    "Voordat we deze functies kunnen gebruiken moeten we eerst de `json`-library importeren."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In het voorbeeld hieronder maken we eerst een Python Dictionary aan:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mytodo = {\"text\": \"Boodschappen supermarkt\", \"done\": 0}\n",
    "mytodo [\"text\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "type(mytodo)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Via `json.dumps` zetten we dit om in een string (tekst).\n",
    "Zo'n tekstformaat kun je zonder problemen communiceren of opslaan op een extern medium: je bent niet afhankelijk van een interne, binaire representatie.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mytodo_string = json.dumps(mytodo)\n",
    "mytodo_string"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Merk op dat deze string-representatie erg lijkt op de oorspronkelijke vorm.\n",
    "Maar het is een gewone string, je kunt er geen velden in selecteren enz."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "type(mytodo_string)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Met de functie `json.loads` zet je deze JSON stringwaarde om in een Python dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "json.loads(mytodo_string)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Ga na wat het type van het resultaat is van de vorige cel.\n",
    "* Ga na dat je in dit resultaat het veld \"done\" kunt selecteren."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### JSON beperkingen\n",
    "\n",
    "JSON heeft maar een beperkt aantal basis-types: number, string, boolean. \n",
    "Dit betekent dat je complexere basistypes zoals *datum* als string moet representeren."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Voorbeeld HTTP met JSON\n",
    "\n",
    "In dit voorbeeld gebruiken we een eenvoudige ToDo-toepassing.\n",
    "Voor deze demonstratie hebben we deze beschikbaar gemaakt op `glitch.com`:\n",
    "https://shadowed-alder.glitch.me/ .\n",
    "Je kunt de broncode bekijken via: https://glitch.com/edit/#!/shadowed-alder?path=server.js"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "todo_app = \"https://shadowed-alder.glitch.me\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Het volgende verzoek levert een JSON-document op met alle todo's:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r1 = requests.get(todo_app + \"/todos\")\n",
    "r1.status_code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Zoals je ziet is het resultaat (de payload) een text in JSON-formaat:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r1.text"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "De requests-library heeft een ingebouwde JSON-decoder.\n",
    "De functie `r1.json()` levert de Python-waarde (hier: list van dictionaries) als resultaat van de decodering."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r1.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We kunnen de gegevens van een enkele todo opvragen, door de `id` hiervan in de URL op te nemen:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r2 = requests.get(todo_app + \"/todos/2\")\n",
    "r2.status_code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mytodo = r2.json()\n",
    "mytodo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### PUT: update\n",
    "\n",
    "Met een `PUT`-request kunnen we de toestand van deze todo veranderen, bijvoorbeeld `done` op 1 zetten."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mytodo['done'] = 1\n",
    "r3 = requests.put(todo_app + \"/todos/2\", data=mytodo)\n",
    "r3.status_code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r3.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### POST: create\n",
    "\n",
    "Een nieuwe todo kunnen we aanmaken met een `POST` naar URL voor de verzameling todo's.\n",
    "De `id` in het resultaat is de identificatie van de todo in de API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "newtodo = {'text': 'Huiswerk maken!', 'done': 0}\n",
    "r4 = requests.post(todo_app + \"/todos\", data=newtodo)\n",
    "r4.status_code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r4.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "todo_id = r4.json()[\"id\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r5 = requests.get(todo_app + \"/todos/{id}\".format(\n",
    "        id = todo_id\n",
    "     ))\n",
    "r5.status_code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r5.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Delete: delete\n",
    "\n",
    "Met de `DELETE` http-method kunnen we een todo ook weer verwijderen.\n",
    "De gebruiken de `id` van de zojuist aangemaakte todo."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r5 = requests.delete(todo_app + \"/todos/{id}\".format(\n",
    "       id = todo_id\n",
    "     ))\n",
    "r5.status_code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r5.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Authenticatie en autorisatie\n",
    "\n",
    "Dit todo-voorbeeld is in één opzicht niet erg praktisch: iedereen kan deze lijst aanpassen.\n",
    "In de praktijk zul je bij zo'n soort toepassing moeten inloggen, met een gebruikersnaam en wachtwoord.\n",
    "Deze combinatie zorgt voor authenticatie: de server weet wie je bent, alleen jij kent deze combinatie (als het goed is ;-).\n",
    "Impliciet zorgt dit ook voor autorisatie: je mag nu gebruik maken van de diensten die aan jouw naam gekoppeld zijn.\n",
    "\n",
    "* authenticatie: ben jij wie je zegt dat je bent? Hoe kun je dat bewijzen?\n",
    "* autorisatie: heb jij hiervoor toestemming?\n",
    "\n",
    "Bij het gebruik van web-api's gebruik je vaak een API-key of een token dat de rol van de gebruikersnaam/wachtwoord vervult.\n",
    "Je kunt als aangemelde gebruiker vaak zo'n key aanmaken. Wees erop bedacht dat je deze net zo vertrouwelijk moet behandelen als je gebruikersnaam/wachtwoord-combinatie!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## openweathermap\n",
    "\n",
    "Via https://openweathermap.org kun je het actuele weer op een bepaalde lokatie ophalen.\n",
    "Je moet daarvoor een gratis account aanmaken.\n",
    "(Met een betaalde account krijg je meer mogelijkheden.)\n",
    "De beschrijving van de API voor het huidige weer vind je via: https://openweathermap.org/current\n",
    "\n",
    "In je account kun je een API-key aanmaken die je nodig hebt als authenticatie/autorisatie,\n",
    "zie de tab API-keys (als je ingelogd bent)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "openweathermap_key = 'vulhierjekeyin'\n",
    "url = 'https://api.openweathermap.org/data/2.5/weather?q={city},{country}&appid={API_key}'.format(\n",
    "        city = \"Amsterdam\",\n",
    "        country = \"nl\",\n",
    "        API_key = openweathermap_key\n",
    "      )\n",
    "rw = requests.get(url)\n",
    "\n",
    "rw.status_code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rw.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "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.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}