Skip to content

Commit

Permalink
[API] New directory for jupyter notebooks (aces#6854)
Browse files Browse the repository at this point in the history 
New Jupyter notebooks to demonstrate how the REST API works.
  • Loading branch information
@spell00 @AlexandraLivadas
spell00 authored and AlexandraLivadas committed Jun 29, 2021
1 parent 342e05a commit f62dc04
Show file tree
Hide file tree
Showing 2 changed files with 2,397 additions and 0 deletions.
248 changes: 248 additions & 0 deletions docs/notebooks/LORIS-API_Part1-HTTP.ipynb
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,248 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#LORIS API Tour 1/2\nThis tutorial is also available as a Google colab notebook so you can run it directly from your browser. To access it, click on the button below: <a href=\"https://colab.research.google.com/github/aces/Loris/blob/main/docs/notebooks/LORIS-API_Part1-HTTP.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## HTTP 1.1"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"**Disclaimer! This is not exhaustive and mostly accurate ** \n",
"*My intention is to present some key concepts that will be used later in the presentation* \n",
"\n",
"\n",
"URLs are ressources addresse that can be access and interact with using predefined methods. \n",
"ex: `https://demo.loris.ca/main.php` is a link for the ressource `main.php` on `demo.loris.ca` \n",
"\n",
"\n",
"Protocol : A client send a **HTTP Request** to a server that should answer with a **HTTP Response**. \n",
" - Requests and Responses have headers and often body\n",
" - Requests uses a Methods\n",
" - Responses have status codes\n",
" \n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### HTTP Request\n",
"##### Methods\n",
" - GET : Retreive a ressource\n",
" - POST : Send data to the server\n",
" - PUT : Replace a ressource\n",
" - PATCH : Partially replace a ressource \n",
" - DELETE : Delete\n",
" - HEAD : Same as GET but without the ressource (headers only)\n",
" \n",
" https://www.restapitutorial.com/lessons/httpmethods.html\n",
" \n",
"##### Headers\n",
"The headers describe the nature of the request or give hint to the server about how to process it.\n",
" - **Accept** *Used for content negociation*\n",
" - **Authorization** *Involved in the authentication process*\n",
" - **Content-Length** *When the request contains a body (POST/PUT/PATCH)*\n",
" - **Content-Type** *When the request contains a body (POST/PUT/PATCH)*\n",
" - ... \n",
" "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### HTTP Response\n",
"#### Status code\n",
" - 1xx: Informational - Request received, continuing process\n",
" - 2xx: Success - The action was successfully received, understood, and accepted\n",
" - 3xx: Redirection - Further action must be taken in order to complete the request\n",
" - 4xx: Client Error - The request contains bad syntax or cannot be fulfilled\n",
" - 5xx: Server Error - The server failed to fulfill an apparently valid request\n",
" \n",
" https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html\n",
" \n",
"**200 OK** \n",
"The request has succeeded. The information returned with the response is dependent on the method used in the request, for example:\n",
"\n",
"*GET* an entity corresponding to the requested resource is sent in the response \n",
"*POST* an entity describing or containing the result of the action \n",
" \n",
" \n",
"**303 See Other** \n",
"The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource. [...]\n",
"\n",
"The different URI SHOULD be given by the **Location field** in the response. [...] \n",
"\n",
"\n",
"**400 Bad Request** \n",
"The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.\n",
"\n",
"**401 Unauthorized** ... _I don't know who you are_ \n",
"The request requires user authentication. \n",
"\n",
"**403 Forbidden** ... _I know who you are and you can't access that ressource_ \n",
"The server understood the request, but is refusing to fulfill it. \n",
"\n",
"**404 Not Found** \n",
"The server has not found anything matching the Request-URI. [...] \n",
"\n",
"**500 Internal Server Error** \n",
"The server encountered an unexpected condition which prevented it from fulfilling the request.\n",
" \n",
"#### Headers\n",
"\n",
"\n",
" - **Content-Length** *When the response contains a body (even for HEAD)*\n",
" - **Content-Type** *The type of data returned* \n",
" - **Location** After a 303 response, the URL to GET the ressource\n",
" - ... \n",
" "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Quick example using curl"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%%bash\n",
"curl -v -s --head https://demo.loris.ca/main.php 2>&1 |grep '[<>]'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### With a html parser user agent (browser)\n",
"https://demo.loris.ca"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### What if I do not want to use a mouse?"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"scrolled": true
},
"outputs": [],
"source": [
"%%bash\n",
"curl -k -i -s \\\n",
" -H 'Content-Type: application/x-www-form-urlencoded' \\\n",
" -d 'username=demo&password=demo&login=Click+to+enter' \\\n",
" https://demo.loris.ca/main.php"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## LORIS API ressources (endpoints)\n",
"\n",
"Our API documentation: https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%%bash\n",
"curl -s https://demo.loris.ca/api/v0.0.3/login -d '{\"username\":\"\", \"password\": \"\"}'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Great, we have a token... now what?"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%%bash\n",
"# Query the /candidates endpoint\n",
"# https://github.com/aces/Loris/blob/minor/docs/API/LorisRESTAPI.md#30-candidate-api\n",
"\n",
"token=''\n",
"curl -k -s \\\n",
" -H \"Authorization: Bearer $token\" \\\n",
" https://demo.loris.ca/api/v0.0.3/candidates/ "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%%bash\n",
"# Query the /candidate_list module\n",
"\n",
"token=''\n",
"curl -k -s \\\n",
" -H \"Authorization: Bearer $token\" \\\n",
" 'https://demo.loris.ca/candidate_list/?format=json'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Scripting and parsing json \n",
" \n",
"see: [part2 - Python script](https://github.com/aces/Loris/blob/main/docs/notebooks/LORIS_API_Part2_Python-script.ipynb)"
]
}
],
"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.3"
}
},
"nbformat": 4,
"nbformat_minor": 2
}
Loading

0 comments on commit f62dc04

Please sign in to comment.