part1-api-workshop-intro.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "8a150ba7-0125-45e0-b055-711b968d9a79",
   "metadata": {},
   "source": [
    "# eLabFTW - API workshop\n",
    "\n",
    "Welcome to this workshop! This project will guide you towards mastering the **eLabFTW** API.\n",
    "\n",
    "It is split in three parts, each in their own notebook (*e.g.* \"part1-api-workshop-intro\"). This first part is introducing base concepts such as HTTP verbs and the REST architecture. The second part explains how to use `curl` (via command-line) to interact with the API, while the third and last part focuses on using the Python library [elabapi-python](https://github.com/elabftw/elabapi-python).\n",
    "\n",
    "### 1. **Introduction**\n",
    "\n",
    "This workshop is suitable for complete beginners as well as advanced users. Participants will learn how to authenticate, retrieve, create, update, and delete entries through API calls. The workshop emphasizes practical, beginner-friendly examples, making it suitable even for those new to REST APIs and Python programming. By the end, attendees will gain confidence in using eLabFTW's API to automate their lab workflows. ✅\n",
    "\n",
    "### 2. **How to navigate through this Notebook**\n",
    "\n",
    "If you are new to **JupyterLab**, the interface might seem a bit unfamiliar at first. This notebook is structured into cells, which you can execute by clicking the Play ( ▶ ) button near each cell, or hit `ctrl` + `enter` when selecting a cell:\n",
    "\n",
    "![image.png](https://github.com/elabftw/api-workshop/blob/master/assets/01-how-to-use-cells.png?raw=true)\n",
    "\n",
    "You can double-click a cell to edit its content.\n",
    "\n",
    "There are two types of cells:\n",
    "\n",
    "- **Markdown cells** (used for text and explanations)\n",
    "- **Executable code cells** (where you can run Python or other code)\n",
    "\n",
    "To fully explore the interactive features of this notebook, you'll need to run specific cells as instructed.\n",
    "\n",
    "## **Chapter 1: Understanding APIs and Essential Tools**\n",
    "\n",
    "### 1. **What is an API**\n",
    "\n",
    "**API (Application Programming Interface)**: A set of rules that allows different software applications to communicate with each other.\n",
    "\n",
    "**REST (Representational State Transfer)**: A style of web API design that uses standard HTTP methods (`GET`, `POST`, `PUT`, `DELETE`) for communication and is stateless.\n",
    "\n",
    "Here are key points to be identified: \n",
    "\n",
    "- There is a client / server architecture: you are the client and the instance of eLabFTW is the server.\n",
    "- Stateless client / server communication: there is nothing stored between requests\n",
    "- The interface is uniform: if something works somewhere, it'll work similarly elsewhere\n",
    "\n",
    "![postman api description](https://github.com/elabftw/api-workshop/blob/master/assets/0-postman-api-description.png?raw=true)\n",
    "\n",
    "*Image © 2024 Postman, Inc.\n",
    "https://www.postman.com/what-is-an-api/*\n",
    "?\n",
    "### 2. **What are API Endpoints?**\n",
    "\n",
    "An API endpoint is a specific URL where an API receives requests and sends responses. Each endpoint represents a different function or resource within eLabFTW.\n",
    "\n",
    "Endpoints typically follow the **RESTful** structure mentioned before, where different HTTP methods (`GET`, `POST`, `PUT`, `DELETE`) perform actions on a resource.\n",
    "\n",
    "Here's a detailed breakdown of how an API URL is structured.\n",
    "\n",
    "![url-sections](https://github.com/elabftw/api-workshop/blob/master/assets/10-url-sections.png?raw=true)\n",
    "\n",
    "<span style=\"color:DarkGoldenRod\"><strong>https://</strong></span>: This is the **protocol**, in this case HTTPS, the language of the web.\n",
    "\n",
    "<span style=\"color:LimeGreen\"><strong>api-workshop.elab.one</strong></span>: This is the **host**, which represents the domain name where the API is hosted.\n",
    "\n",
    "<span style=\"color:Blue\"><strong>api/v2/</strong></span>: This indicates the **API versioning**, showing that this request is targeting version 2 of the API. It allows for maintainability and adaptability.\n",
    "\n",
    "<span style=\"color:BlueViolet\"><strong>experiments</strong></span>: This is the **endpoint**, specifying that we are accessing the \"experiments\" resource.\n",
    "\n",
    "<span style=\"color:OrangeRed\"><strong>42</strong></span>: This is the **ID**, identifying a specific experiment within the \"experiments\" endpoint.\n",
    "\n",
    "\n",
    "By combining **headers** with **endpoints**, we can securely and effectively interact with an API.\n",
    "\n",
    "### 3. **What are Verbs?**\n",
    "\n",
    "HTTP verbs (also called HTTP methods) define the type of action to perform when making a request to an API. They specify whether you are retrieving data, sending new data, updating existing data, or deleting information.\n",
    "\n",
    "#### **Basic example of using verbs on an API Endpoint:** `users`\n",
    "- `GET https://api.example.com/users` → **Retrieves** a list of users.\n",
    "- `POST https://api.example.com/users` → **Creates** a new user.\n",
    "- `GET https://api.example.com/users/123` → **Retrieves** details of a **specific** user.\n",
    "- `PATCH https://api.example.com/users/123` → **Updates** a specific user's details.\n",
    "- `DELETE https://api.example.com/users/123` → **Deletes** a specific user.\n",
    "\n",
    "### 3. **What are API Headers?**\n",
    "\n",
    "API headers are key-value pairs sent along with an HTTP request to provide additional information to the server. They help control how the request is processed and can include details like content type, authentication, and caching instructions.\n",
    "\n",
    "**Common API Headers:**\n",
    "- `Authorization`: Used to send authentication credentials (e.g., tokens, API keys).\n",
    "- `Content-Type`: Specifies the type of data being sent (e.g., `application/json`).\n",
    "- `Accept`: Indicates the type of response the client expects (e.g., `application/json`).\n",
    "- `User-Agent`: Identifies the client making the request.\n",
    "\n",
    "### 4. **Combine this knowledge to make a request**\n",
    "\n",
    "You can make requests to the API using <b>curl</b>, a command-line tool used to make HTTP requests. It is commonly used for making API requests, testing endpoints, and automating web interactions.\n",
    "\n",
    "**Example: Sending a request with headers using cURL**\n",
    "\n",
    "Now, let's put everything together and see what a complete `curl` request looks like. Notice that since no HTTP verb (GET, POST, *etc.*) is explicitly specified, it defaults to GET:\n",
    "\n",
    "```sh\n",
    "curl https://elab.example.org/api/v2/users -H \"Authorization: YOUR_API_KEY\" -H \"Content-Type: application/json\" \n",
    "```\n",
    "\n",
    "## **Chapter 2: eLabFTW's API**\n",
    "\n",
    "### 1. **Some specifications**\n",
    "\n",
    "Let us focus on the eLabFTW API. Here are some specifications to have in mind:\n",
    "\n",
    "- Available at `/api/v2/`. *e.g.* https://elab.example.org/api/v2/.\n",
    "    - Versioning ensures a stable and predictable integration experience for users. The API is in **version 2 (v2)** to introduce improvements, fixes, and new features while maintaining compatibility with older versions. \n",
    "- Tools to access it:\n",
    "    - Your browser (defaults as GET requests). This is sent when you paste the url in your searchbar.\n",
    "    - `curl` (command-line tool)\n",
    "    - Anything able to make an HTTP request (virtually all programming languages such as Python, R, or Ruby)\n",
    "- Uses HTTP verbs for different actions:\n",
    "    - **Create** → `POST`\n",
    "    - **Read** → `GET`\n",
    "    - **Update** → `PATCH`\n",
    "    - **Delete** → `DELETE`\n",
    "\n",
    "These actions brought together are often referred to as `CRUD`.\n",
    "\n",
    "### 2. **HTTP Status Codes (Response Codes and Their Meaning)**\n",
    "\n",
    "Here is a non exhaustive list of the status code you might obtain while using eLabFTW's API:\n",
    "\n",
    "- 200 OK: The request was successful, and the response contains the requested data.\n",
    "- 201 Created: The resource was successfully created, and no further content is returned.\n",
    "- 400 Bad Request: The request was invalid or malformed, requiring modification before submitting again.\n",
    "- 401 Unauthorized: Authentication is required.\n",
    "- 403 Forbidden: You cannot access this resource.\n",
    "- 404 Not Found: You know this one ;)\n",
    "- 405 Method Not Allowed: If the HTTP verb is not supported on this endpoint.\n",
    "- 50X Server Error: An issue occurred on the server side, preventing the request from being processed.\n",
    "\n",
    "#### **Illustration of simple requests**\n",
    "> ![example of simple requests](https://github.com/elabftw/api-workshop/blob/master/assets/02-example-of-basic-requests.png?raw=true)\n",
    "\n",
    "\n",
    "**Congratulations on completing the first part of the course!** Now, we can move on to making our own `curl` requests via the command line.\n",
    "\n",
    " ➡️ See [part two](./part2-api-workshop-curl.ipynb) of this course."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.13.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}