4-api/APIs.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### APIs\n",
    "\n",
    "An Application Programming Interface (API) is a server than enables you to send and, more commonly, receive data. In python there are several libraries that can be used to call APIs, the most commonly used of which is the `requests` library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are several commands that can be used on an API. The most useful of which is the GET command, which enables a user to receive data from the API. To use the GET command, we pass a URL that provides the address of the data we want to fetch.\n",
    "\n",
    "For example, we can fetch information about the current astronauts on the International Space Station."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "200"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = requests.get(\"https://api.frankfurter.app/latest?\")\n",
    "response.status_code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The status code 200 indicates the request was successful.\n",
    "\n",
    "- 200 – OK. The request was successful.\n",
    "- 204 – No Content. The server successfully processed the request and did not return any content.\n",
    "- 301 – Moved Permanently. The server responds that the requested page (endpoint) has been moved to another address and redirects to this address.\n",
    "- 400 – Bad Request. The server cannot process the request because the client-side errors (incorrect request format).\n",
    "- 401 – Unauthorized. Occurs when authentication was failed, due to incorrect credentials or even their absence.\n",
    "- 403 – Forbidden. Access to the specified resource is denied.\n",
    "- 404 – Not Found. The requested resource was not found on the server.\n",
    "- 500 – Internal Server Error. Occurs when an unknown error has occurred on the server.\n",
    "    \n",
    "A status code that begins with \n",
    "- 2 indicates a successful operation\n",
    "- 3 indicates a redirection (that was successful)\n",
    "- 4 indicates a client error (i.e. by you)\n",
    "- 5 indicates a server erorr (i.e. by them)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The resonse is given in JSON format, which is very similar to a Python dict. Calling json() on the response converts the JSON into a Python dict."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'amount': 1.0,\n",
       " 'base': 'EUR',\n",
       " 'date': '2021-10-12',\n",
       " 'rates': {'AUD': 1.566,\n",
       "  'BGN': 1.9558,\n",
       "  'BRL': 6.3977,\n",
       "  'CAD': 1.4395,\n",
       "  'CHF': 1.0729,\n",
       "  'CNY': 7.4522,\n",
       "  'CZK': 25.376,\n",
       "  'DKK': 7.4408,\n",
       "  'GBP': 0.84755,\n",
       "  'HKD': 8.9915,\n",
       "  'HRK': 7.5155,\n",
       "  'HUF': 359.91,\n",
       "  'IDR': 16397,\n",
       "  'ILS': 3.7275,\n",
       "  'INR': 87.27,\n",
       "  'ISK': 150.0,\n",
       "  'JPY': 131.06,\n",
       "  'KRW': 1383.4,\n",
       "  'MXN': 24.023,\n",
       "  'MYR': 4.8132,\n",
       "  'NOK': 9.8608,\n",
       "  'NZD': 1.6591,\n",
       "  'PHP': 58.711,\n",
       "  'PLN': 4.5805,\n",
       "  'RON': 4.9499,\n",
       "  'RUB': 83.02,\n",
       "  'SEK': 10.1078,\n",
       "  'SGD': 1.5664,\n",
       "  'THB': 38.501,\n",
       "  'TRY': 10.4044,\n",
       "  'USD': 1.1555,\n",
       "  'ZAR': 17.265}}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "exr = response.json()\n",
    "exr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The API has provided conversion rates from Euros to 32 other currencies for today's date."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "32"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(exr['rates'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can easily find the exchange rate for a specific currency."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.84755"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "exr['rates']['GBP']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, the API has converted from Euros for the current date. To get information on other currencies, we can pass parameters within the URL.\n",
    "\n",
    "We pass the parameters\n",
    "\"amount=10\" to provide the amount of the currecnty (e.g. £10)\n",
    "\"from=GPB\" to indicate we want to convert from British Sterling\n",
    "\"to=USD,EUR\" to indicate we want to conver to US dollars and Euros."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'amount': 10.0,\n",
       " 'base': 'GBP',\n",
       " 'date': '2021-10-12',\n",
       " 'rates': {'EUR': 11.7987, 'USD': 13.6334}}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "response = requests.get('https://api.frankfurter.app/latest?&amount=10&from=GBP&to=USD,EUR')\n",
    "response.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make our code more legible, we can store parameters in a separate dict object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'amount': 10.0,\n",
       " 'base': 'GBP',\n",
       " 'date': '2021-10-12',\n",
       " 'rates': {'USD': 13.6334}}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "url = 'https://api.frankfurter.app/latest'\n",
    "parameters = {'amount': 10,\n",
    "              'from': 'GBP',\n",
    "              'to': 'USD'}\n",
    "\n",
    "response = requests.get(url, params=parameters)\n",
    "response.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API keys"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many APIs request that you sign up for an API key, even if the service is free. This enables the service provider to measure, track and restrict API usage. For example, to understand which features are the most popular (i.e. used by the most unique people) and to help prevent Denial of Service attacks.\n",
    "\n",
    "If an API key is required, it is simply passed as an additional parameter in the URL.\n",
    "\n",
    "In the case that the API is not free, passing an API key is considered safer than passing credentials (such as a username and password) within the parameters of a URL."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other method calls\n",
    "\n",
    "In these examples, we have only used the GET command, but there are several others. These are:\n",
    "- **POST** Create a new resource (i.e. add new data to the server).\n",
    "- **PUT** Update an existing resource (i.e. completely replace the data on the server).\n",
    "- **PATCH** Partially update an existing resource (i.e. change a specific value on the server). \n",
    "- **DELTE** Delete a resource."
   ]
  }
 ],
 "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.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}