02-basic-resources.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<img style=\"float: right; padding: 10px;\" width=\"200\" src=\"images/logo-onem2m-the-iot-standard.jpg\">\n",
    "\n",
    "# oneM2M - Basic Resources and Requests\n",
    "This notebook shows the basic interactions with a CSE using REST calls. Examples include:\n",
    "\n",
    "- Create an &lt;AE> resource\n",
    "- Create a &lt;container> resource\n",
    "- Create one or more &lt;contentInstance> resources\n",
    "- Retrieve the latest &lt;contentInstance> resource\n",
    "- Update the &lt;container> resource\n",
    "- Retrieve the &lt;container> resource\n",
    "- Delete the &lt;container> resource\n",
    "\n",
    "\n",
    "## Intitialization\n",
    "The section does import necessary modules and configurations, and prepares the CSE for this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "%run src/init.py basic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "## Register an &lt;AE> Resource\n",
    "\n",
    "<img align=\"right\" src=\"images/02/register_AE.png\">\n",
    "\n",
    "\n",
    "This example creates a new &lt;AE> resource in the CSE. &lt;AE>'s represent applications or services.\n",
    "\n",
    " \n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        Creating this (and other) resource is done using an http POST request.<br>\n",
    "        The request target is the &lt;CSEBase> resource. All create requests target a parent resource.<br>\n",
    "        <br>\n",
    "        When registering a new &lt;AE> resource it will be the entity on which behalf further requests can be made. The ID to identify this &lt;AE> is provided by the CSE in the <i>App-ID</i> attribute.\n",
    "        Normally, this ID is assigned by the CSE, but we can also ask the CSE to use a pre-defined ID, that is given in the <i>originator</i> header in the request. It must start with an uppercase \"C\".\n",
    "    </div>\n",
    "</div>\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "CREATE (                                                     # CREATE request\n",
    "    \n",
    "    # Create the AE resource under the CSEBase\n",
    "    to                      = cseBaseName,  \n",
    "    \n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',                     # Assign an originator ID, must start with 'C'\n",
    "    requestIdentifier       = '123',                         # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                           # Release version indicator\n",
    "    resourceType            = Type.AE,                       # Type of the resource: AE\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {   \n",
    "            'm2m:ApplicationEntity': {\n",
    "                'resourceName':             'Notebook-AE',   # Name of the resource \n",
    "                'App-ID':                   'NnotebookAE',   # Application ID, must start with 'N'\n",
    "                'requestReachability':      True,            # AE can receive requests\n",
    "                'supportedReleaseVersions': [ '3' ]          # Supports oneM2M release 3\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Requests & Response Attributes\n",
    "\n",
    "The request and response introduce new attributes:\n",
    "\n",
    "| Attribute           | Short Name | Description                                                                                                                                                 |\n",
    "|:--------------------|:-----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------|\n",
    "| APP-ID              | api        | Application Identifier. An Application Identifier uniquely identifies an M2M Application in a given context.                                                |\n",
    "| requestReachability | rr         | Request Reachability. This attribute indicates whether an entity can directly receive requests.                                                             |\n",
    "| parentID            | pi         | Since oneM2M organizes resources in a tree structure almost all resources have a parent resource. This is the identifier that links to the parent resource. |\n",
    "| expirationTime      | et         | Expiration time/date after which the CSE will delete the resource.                                                                                          |\n",
    "| AE-ID               | aei        | An Application Entity Identifier uniquely identifies an AE globally.<br>In our case this is the same ID as the provided *originator*.                       |\n",
    "\n",
    "<img align=\"right\" src=\"images/02/create_container.png\">\n",
    "\n",
    "## Create a &lt;container> Resource\n",
    "In this section we add a &lt;container> resource to the &lt;AE> resource. A &lt;container> represents a structure in the oneM2M resource tree that can have a configurable number of data instances as child resources. A &lt;container> resource may also have further &lt;container> child-resources.\n",
    "\n",
    "If created with no further attributes, the CSE will assign meaningful defaults to the &lt;container> resource's attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CREATE (                                      # CREATE request\n",
    "    \n",
    "    # Create the container resource under the AE\n",
    "    to                      = cseBaseName + '/Notebook-AE', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',      # Set the originator\n",
    "    requestIdentifier       = '123',          # Unique request identifier\n",
    "    releaseVersionIndicator = '3',            # Release version indicator\n",
    "    resourceType            = Type.Container, # Type of the resource: container\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'm2m:Container': {\n",
    "                'resourceName': 'Container'   # Set the resource name\n",
    "            }\n",
    "        },\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        A &lt;container> has two virtual child resources, <i>latest</i> (la) and <i>oldest</i> (ol), which virtually represent the latest and oldest &lt;contentInstance> resources, respectively. \n",
    "        They can only receive RETRIEVE and DELETE requests.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "\n",
    "<p>\n",
    "<div  style=\"background-color:transparent;border:2px #005480 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#005480;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; Note</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        If you see an error \"409\" or \"Name already present\" then don't worry. It just means that an &lt;container> resource with the same name already exists in the CSE, perhaps from a previous run of this notebook cell.    \n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "### Requests & Response Attributes\n",
    "\n",
    "The request and response introduce new attributes:\n",
    "\n",
    "| Attribute            | Short Name | Description                                                                                             |\n",
    "|:---------------------|:-----------|:--------------------------------------------------------------------------------------------------------|\n",
    "| currentNrOfInstances | cni        | Current number of direct &lt;contentInstance> resources under the &lt;Container> resource.              |\n",
    "| currentByteSize      | cbs        | Totel of the size in bytes of data in the &lt;contentInstance> resources.                               |\n",
    "| stateTag             | st         | The <i>stateTag</i> is incremented every time a new &lt;contentInstance> is created as a child resource |\n",
    "\n",
    "\n",
    "\n",
    "## Add a &lt;contentInstance> to the &lt;container>\n",
    "\n",
    "<img align=\"right\" src=\"images/02/create_contentInstance.png\">\n",
    "\n",
    "Now, we add some data to the *myContainer* &lt;container>. \n",
    "\n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        &lt;contentInstance> resources can only be added and read, but not updated or deleted.<br>\n",
    "        <br>\n",
    "        In the following request we don't provide a resource name. Instead, we let the CSE provide one for the newly created resource.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "<p>\n",
    "<div  style=\"background-color:transparent;border:2px #005480 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#005480;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; Note</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        You can execute the following code as often as you like to create more &lt;contentInstance> resources.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CREATE (                                            # CREATE request\n",
    "\n",
    "    # Create the content instance resource under the container\n",
    "    to                      = cseBaseName + '/Notebook-AE/Container', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    "    resourceType            = Type.ContentInstance, # Type of the resource: contentInstance\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'm2m:ContentInstance': {\n",
    "                'contentInfo': 'text/plain:0',      # Media type of the content\n",
    "                'content': 'Hello, World!'          # The content itself\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Requests & Response Attributes\n",
    "\n",
    "The request and response introduce new attributes:\n",
    "\n",
    "| Attribute   | Short Name | Description                                                                                                                                    |\n",
    "|:------------|:-----------|:-----------------------------------------------------------------------------------------------------------------------------------------------|\n",
    "| contentInfo | cnf        | This attribute specifies the content format. It specifies the media type as well as the encoding type (0 means \"plain, no transfer encoding\"). |\n",
    "| content     | con        | This is the actual content (ie. the value) that will be stored for the data point.                                                             |\n",
    "| contentSize | cs         | This attribute contains the size of the data in the *content* attribute.                                                                       |\n",
    "\n",
    "<img align=\"right\" src=\"images/02/retrieve_contentInstance.png\">\n",
    "\n",
    "\n",
    "## Retrieve the latest created &lt;contentInstance> resource\n",
    "This request will retrieve the latest data instance from the &lt;container>.\n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        The <em>resourceType</em> attribute is not necessary to provide in RETRIEVE requests, only in CREATE.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    " "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RETRIEVE (                                          # RETRIEVE request\n",
    "\n",
    "    # Retrieve the latest <contentInstance> resource under the container\n",
    "    to                      = cseBaseName + '/Notebook-AE/Container/la', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"right\" src=\"images/02/update_container.png\">\n",
    "\n",
    "\n",
    "## Update the &lt;container> Resource\n",
    "\n",
    "With this request we will set the *maxNumberOfInstances* attribute in the &lt;container> resource. This will restrict the number of &lt;contentInstance> resources for this &lt;container>.\n",
    " \n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "        It is only necessary to provide the attributes we want to update in the request, not the whole resource.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "UPDATE (                                            # UPDATE request\n",
    "\n",
    "    # Target the container resource\n",
    "    to                      = cseBaseName + '/Notebook-AE/Container', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'm2m:Container': {\n",
    "                 'maxNrOfInstances': 10            # Set the maxNumberOfInstances to 10\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The CSE returns the updated &lt;container> resource. \n",
    "\n",
    " \n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "    Also note the change of the <i>lastModificationTime</i> attribute. It is set to a new time, namely the time of the update.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "\n",
    "### Requests & Response Attributes\n",
    "\n",
    "The request and response introduce new attributes:\n",
    "\n",
    "| Attribute            | Short Name | Description                                                                                             |\n",
    "|:---------------------|:-----------|:--------------------------------------------------------------------------------------------------------|\n",
    "| maxNrOfInstances     | mni        | Maximum number of direct &lt;contentInstance> resources under the &lt;Container> resource.              |\n",
    "\n",
    " \n",
    "\n",
    "<img align=\"right\" src=\"images/02/retrieve_container.png\">\n",
    "\n",
    "## Retrieve the &lt;container> Resource\n",
    "Retrieve the &lt;container> resource to see all the changes and its current state."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RETRIEVE (                                          # RETRIEVE request\n",
    "\n",
    "    # Retrieve the container resource\n",
    "    to                      = cseBaseName + '/Notebook-AE/Container', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The CSE returns the resource.\n",
    "\n",
    "<img align=\"right\" src=\"images/02/delete_container.png\">\n",
    "\n",
    "## Delete the &lt;container> Resource\n",
    "\n",
    "The last request in this lecture removes the &lt;container> resource from the CSE's oneM2M resource tree.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "DELETE (                                            # DELETE request\n",
    "\n",
    "    # Delete the container resource\n",
    "    to                      = cseBaseName + '/Notebook-AE/Container', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " <p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 350px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "When a resource is deleted then all its child resources, for example in our example the &lt;contentInstance> resources, are deleted as well.\n",
    "    </div>\n",
    "</div>\n",
    "</p>"
   ]
  }
 ],
 "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.8.7"
  },
  "toc-autonumbering": false,
  "toc-showmarkdowntxt": false,
  "toc-showtags": true
 },
 "nbformat": 4,
 "nbformat_minor": 4
}