25. Implementing REST in Python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*********************************************************************************************************\n",
    "# A Tour of Python 3  \n",
    "version 1.0.1  \n",
    "Authors: Phil Pfeiffer, Zack Bunch, and Feyisayo Oyeniyi  \n",
    "East Tennessee State University  \n",
    "Last updated June 2021  \n",
    "\n",
    "Chapter 25: author Edgar Guerra, ed. Phil Pfeiffer  \n",
    "*********************************************************************************************************"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 25. Implementing REST in Python  \n",
    " 25.1 [Interfaces, APIs, and API Architectures](#REST-Interfaces-API-and-API-Architectures)  \n",
    " 25.2 [REST](#REST-REST)  \n",
    " 25.3 [Support for REST-Based Data Access](#REST-Support-for-REST-Based-Data-Access)   \n",
    " &ensp; 25.3.1 [JSON](#REST-JSON)    \n",
    " &ensp; 25.3.2 [HTTP](#REST-HTTP)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 25.1 Interfaces, APIs, and API Architectures <a name='REST-Interfaces-API-and-API-Architectures'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An *interface* is a control, or a set of controls, that affords access to a system’s state and/or operation.",
    " A common example of an interface is an automobile’s dashboard.",
    " A dashboard contains controls that enable a driver to start, drive, monitor, and stop a car without understanding how a car’s components operate.\n",
    "\n",
    "An Application Programmable Interface (API) is an interface through which components can access a software component’s state and/or functionality.",
    " APIs take different forms, depending on the requirements that they need to address.",
    " For example, an API can be designed to support stateful or stateless interactions between two interacting components:",
    " the former assumes that the components “remember” information about the sequence of interactions,",
    " while the latter requires each interaction to be self-contained.",
    " In a network environment, an API can be designed to “hide” the network — i.e., to blur the distinction between requests and procedure calls — or expose it.",
    " The elements of an API’s interface can be given standard or custom names — again, depending on a system’s requirements.\n",
    "\n",
    "A set of well-known guidelines for designing an APIs is known as an API architecture.  Some common API architectures include RPC, SOAP, and REST."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 25.2 REST  <a name='REST-REST'></a>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The REST (REpresentational State Transfer) architecture for network-based service access was devised by Roy Fielding, ",
    "who introduced it in his 2000 Ph.D. dissertation. ",
    "Before Fielding, standard APIs for network-based service access assumed the use of remote procedure call (RPC): ",
    "the use of network-aware procedure calls to blur the distinction between local and networked services. ",
    "Fielding argued that protocols for network-based service access must expose the challenges of networked communications to designers, ",
    "in order to allow for efficient approaches for addressing network-specific communications difficulties ",
    "such as server crashes, network latency, and limitations on communications bandwidth. \n",
    "\n",
    "Among its other features, Fielding’s architecture uses stateless communication as a means of simplifying crash recovery ",
    " and transparent, network-based caching of content as a means of reducing latency and conserving bandwidth. ",
    "\n",
    "As a basis for his architecture, Fielding defined HTTP, including the semantics of GET, PUT, and POST and the error codes for responding to problem requests.\n",
    "A RESTful API is one that meets Fielding’s five constraints for API interaction:\n",
    "- The API must provide client-server-style, request-response-based communications via HTTP.\n",
    "- Communications must be stateless: i.e., every request supplies all context needed to fulfill the request, ",
    "including (e.g.) proof of the requestor’s authority to make the request. ",
    "Statelessness simplifies server maintenance and crash recovery by eliminating the need for servers to restart dialogues following crashes.\n",
    "- Responses must be cacheable. This allows for the network to reduce communications latency by storing served content closer to its requestors.",
    " Users, however, must be wary of stale data.\n",
    "- The API must provide a uniform interface. This includes support for the ability to query an interface’s version and data formatting protocols.\n",
    "- The API must allow for a layered implementation. ",
    "This allows for the use of load balancers to distribute traffic or the addition of network-based security measures like gateways.\n",
    "\n",
    "For more information on REST, consult ",
    "<a href=\"https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm\" target=\"_blank\">Fielding’s (highly readable) Ph.D. dissertation.<a/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 25.3 Support for REST-Based Data Access <a name=\"REST-Support-for-REST-Based-Data-Access\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 25.3.1 JSON <a name='REST-JSON'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The JSON (JavaScript Object Notation) is one of several common markup-language-based standards for exchanging metadata-qualified content. ",
    "JSON’s popularity is due in large part to its lightweight syntax and JQuery’s built-in support for JSON messaging.\n",
    "\n",
    "A JSON document is similar in form to a python dictionary. The following example illustrates Python library support for exchanging JSON data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 25.3.1.a.  Example of json.loads, which converts a JSON string to a python dict\n",
    "\n",
    "#import the json library\n",
    "import json\n",
    "\n",
    "# creating a string named colors in json format\n",
    "colors = '{ \"colors\": [ {\"color\": \"blue\"},{\"color\": \"red\"},{\"color\": \"green\"}] }'\n",
    "\n",
    "# turns a json string into a python dict \n",
    "colorsJSON = json.loads(colors)\n",
    "print(\"Prints out string as a json object: \\n\",colorsJSON,\"\\n\\ntype(colorsJSON): \",type(colorsJSON))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#  25.3.1.b  Example of how to format a JSON object \n",
    "\n",
    "#import the json library\n",
    "import json\n",
    "\n",
    "# creating a string named colors in json format\n",
    "colors = '{ \"colors\": [ {\"color\": \"blue\"},{\"color\": \"red\"},{\"color\": \"green\"}] }'\n",
    "\n",
    "# turns a json string into python object \n",
    "colorsJSON = json.loads(colors)\n",
    "\n",
    "# formats the json object to a formatted string \n",
    "formattedColorsJSON = json.dumps(colorsJSON, indent=4, sort_keys=True)\n",
    "print(\"formattedColorsJSON using json.dumps(): \\n\", formattedColorsJSON)\n",
    "\n",
    "# returns formattedColorsJSONs type \n",
    "print(\"\\n\\nformattedColorsJSON type: \\n\",type(formattedColorsJSON))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#  25.3.1.c  Converting a python dictionary to a json object and parsing through to get the colors\n",
    "\n",
    "#import the json library\n",
    "import json\n",
    "\n",
    "# dictionary object with colors \n",
    "colors = '{ \"colors\": [ {\"color\": \"blue\",\"type\":\"main\"},{\"color\": \"red\",\"type\":\"main\"},{\"color\": \"green\",\"type\":\"main\"}] }'\n",
    "parseColors = json.loads(colors)\n",
    "# loop through and access the colors\n",
    "for color in parseColors['colors']:\n",
    "  print(color)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 25.3.1.1:**\n\n",
    "</span>",
    "<span style='color:navy' >",
    "In the following code cell, ",
    "write a program that grabs the individual colors from the colors string. \n",
    "Example output:  \n",
    "blue  \n",
    "red  \n",
    "green  ",
    "</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 25.3.2  HTTP<a name='REST-HTTP'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "HTTP and its secure variant, HTTPS, are the standard protocols for communicating with RESTful APIs. ",
    "HTTP provides five basic methods for supporting CRUD (create, read, update, delete) operations on persistent content:\n",
    "\n",
    "- `POST`  - used to create content\n",
    "- `GET`   - used to read content\n",
    "- `PUT`   - used to update/replace content\n",
    "- `PATCH` - used to update/modify content\n",
    "- `DELETE`- used to delete content\n",
    "\n",
    "Python’s requests library supports HTTP-based communications between a program’s components."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "#  25.3.2  Example for a successful get request using the request library and json \n",
    "\n",
    "import requests\n",
    "import json\n",
    "\n",
    "# this website supports the testing of HTTP requests.\n",
    "base = \"https://jsonplaceholder.typicode.com\"\n",
    "# to access users, add /users to the base URL\n",
    "getUsersURI = base+\"/users\"\n",
    "#use GET to get the users\n",
    "response = requests.get(getUsersURI) \n",
    "# print the status code and the response\n",
    "# if the request succeeded, the status code will be 200\n",
    "print(\"status code: \", response.status_code)\n",
    "print(json.dumps(response.json(),indent=4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 25.3.2.1:**\n\n",
    "</span>",
    "<span style='color:navy' >",
    "In the following code cell, ",
    "write a program that grabs a user’s \"name\" and \"username\" using the /users URI.",
    "</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "impressed-stocks",
   "metadata": {},
   "outputs": [],
   "source": [
    "#  25.3.2.b Make an unsuccessful GET request using the request library and json \n",
    "\n",
    "import requests\n",
    "import json\n",
    "\n",
    "# this website supports the testing of HTTP-based requests.\n",
    "base = \"https://jsonplaceholder.typicode.com\"\n",
    "\n",
    "# to access users, add /users to the base URL\n",
    "# this call should fail\n",
    "getUsersURI = base+\"/user\"\n",
    "\n",
    "# use GET to make what should be a failed call\n",
    "response = requests.get(getUsersURI) \n",
    "# print the status code and the response, which should be a 404 error\n",
    "#this API violates the uniform interface constraint, since it doesn't return a self-descriptive message\n",
    "print(\"status code: \", response.status_code)\n",
    "print(json.dumps(response.json(),indent=4))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "documented-opening",
   "metadata": {},
   "outputs": [],
   "source": [
    "#  25.3.2.c  Make a successful POST using the request library and json \n",
    "\n",
    "import requests\n",
    "import json\n",
    "\n",
    "# this website supports the testing of HTTP requests.\n",
    "base = \"https://jsonplaceholder.typicode.com\"\n",
    "# this query will be used to pass in the POST request\n",
    "query = {\n",
    "    'title': \"My First Post\",\n",
    "    'body': \"I wrote this post using an API\",\n",
    "    'userId': 1\n",
    "}\n",
    "# the post's URI is a list of dummy posts\n",
    "postPostsURI = base+\"/posts\"\n",
    "\n",
    "# this is an example of how to use POST to make a POST request to a website\n",
    "response = requests.post(postPostsURI,data = query)\n",
    "# the status code returned should be 201 meaning it was successfully created\n",
    "print(\"status code: \", response.status_code)\n",
    "print(json.dumps(response.json(),indent=4))"
   ]
  }
 ],
 "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.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}