Professional Documents
Culture Documents
The contents of this document can be changed or added regularly, and the relevant corrected
version will be added to the document under the title named “New Edition” in consecutive
order. The product or program mentioned in this document may be changed or modified
without any prior notice.
The source code of Mobius Yellow Turtle is distributed according to the license policy below.
The open source code shared by OCEAN (Open allianCE for iot stANdard) is
distributed based on the 3-clause BSD-style license. While maintaining copyright
header in the source code file, the open source code can be used freely in the purpose
of commercial or non-commercial systems.
License of OCEAN does not force users to share the developed source code with
others. The ownership of the developed source code belongs to the developer and
(s)he has no obligation to share it.
Page-2
Mobius-Yellow Turtle REST APIs
/**
* Copyright (c) 2015, OCEAN
* All rights reserved.
* Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:
* 1. Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials provided
with the distribution.
* 3. The name of the author may not be used to endorse or promote products derived from
this software without specific prior written permission.
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
*/
Page-3
Mobius-Yellow Turtle REST APIs
Content
1. Mobius OPEN REST APIs ............................................................................................................................ 6
1.1. REST APIs ............................................................................................................................................. 6
1.2. Common HTTP Header Field Settings ................................................................................................... 6
1.3. oneM2M Data Types Reference ............................................................................................................. 8
1.4. Result Content reference ......................................................................................................................... 9
1.5. Short name representation ...................................................................................................................... 9
1.5.1. Resource and specialization type short name ................................................................................ 9
1.5.2. Resource attribute short names.................................................................................................... 11
1.5.3. Primitive parameter short names ................................................................................................. 14
1.5.4. Complex data types members...................................................................................................... 14
2. OPEN APIs ........................................................................................................................................... 15
2.1. API Outline ................................................................................................................................. 15
2.2. API Details .................................................................................................................................. 16
2.2.1 Abbreviations and Preferences ................................................................................... 16
1) Abbreviations ............................................................................................................. 16
2) Preferences ................................................................................................................. 17
2.2.2 <CSEBase> Resource ................................................................................................ 17
1) API-CB-C ................................................................................................................... 17
2) API-CB-R ................................................................................................................... 17
3) API-CB-U................................................................................................................... 19
4) API-CB-D................................................................................................................... 19
2.2.3 <remoteCSE> Resource ............................................................................................. 19
1) API-CSR-C................................................................................................................. 20
2) API-CSR-R................................................................................................................. 25
3) API-CSR-U ................................................................................................................ 26
4) API-CSR-D ................................................................................................................ 29
2.2.4 <AE> Resource .......................................................................................................... 31
1) API-AE-C ................................................................................................................... 32
2) API-AE-R ................................................................................................................... 34
3) API-AE-U................................................................................................................... 36
4) API-AE-D................................................................................................................... 38
2.2.5 <Container> Resource ................................................................................................ 39
1) API-CNT-C ................................................................................................................ 40
2) API-CNT-R ................................................................................................................ 43
3) API-CNT-U ................................................................................................................ 44
4) API-CNT-D ................................................................................................................ 46
2.2.6 <ContentInstance> Resource ...................................................................................... 46
1) API-CIN-C ................................................................................................................. 47
2) API-CIN-R ................................................................................................................. 49
3) API-CIN-D ................................................................................................................. 50
2.2.7 <SemanticDecriptor> Resource.................................................................................. 51
1) API-SD-C ................................................................................................................... 52
2) API-SD-R ................................................................................................................... 53
3) API-SD-U ................................................................................................................... 55
4) API-SD-D ................................................................................................................... 56
2.2.8 Resource Discovery and Conditional Retrieval .......................................................... 57
1) API-DIS-ResourceType .............................................................................................. 60
2) API-DIS-Label ........................................................................................................... 61
3) API-DIS-Limit ........................................................................................................... 63
Page-4
Mobius-Yellow Turtle REST APIs
4) API-DIS-CreatedBefore&CreatedAfter ..................................................................... 64
5) API-DIS-offset ........................................................................................................... 65
6) API-DIS-Level ........................................................................................................... 66
7) API-DIS-Multiple-Filters ........................................................................................... 67
2.2.9 <Subscription> Resource ........................................................................................... 68
2.2.9.1 Introduction ........................................................................................................ 68
2.2.9.2 Notification Working Principle .......................................................................... 68
2.2.9.3 Subscription CRUD API .................................................................................... 72
1) API-SUB-C ........................................................................................................ 72
2) API-SUB-R ........................................................................................................ 74
3) API-SUB-U ........................................................................................................ 75
4) API-SUB-D ........................................................................................................ 77
2.2.9.4 Use cases: Application of subscription and notification mechanism ................. 78
Use Case I: Subscription and notification for smart application monitoring ................ 79
Secenario I: Notification-for-update-of-subscribed-to-resource ........................... 79
Secenario II: Notification-for-child-creation-of-subscribed-to-resource .............. 84
Secenario III: Notification-for-child-delete-of-subscribed-to-resource ................ 88
Use Case II: Subscription and notification for device control ...................................... 93
Secenario I: Notification-for-device-control ......................................................... 93
2.2.10 <Group> Resource ..................................................................................................... 97
1) API-GRP-C ................................................................................................................ 99
2) API-GRP-R .............................................................................................................. 100
3) API-GRP-U .............................................................................................................. 101
4) API-GRP-D .............................................................................................................. 103
2.2.11 <TimeSeries> Resource............................................................................................ 104
1) API-TS-C ................................................................................................................. 105
2) API-TS-R ................................................................................................................. 107
3) API-TS-U ................................................................................................................. 108
4) API-TS-D ................................................................................................................. 109
2.2.12 <timeSeriesInstance> Resource................................................................................ 110
1) API-TSI-C ................................................................................................................ 111
2) API-TSI-R ................................................................................................................ 112
3) API-TSI-U ................................................................................................................ 113
4) API-TSI-D ................................................................................................................ 114
References: ..................................................................................................................................................... 115
oneM2M Specifications: ............................................................................................................. 115
Page-5
Mobius-Yellow Turtle REST APIs
The Mobius-yt REST APIs is used to upload data generated by embedded IoT devices to Mobius-yt platform as
well as data retrieve services. The Mobius-yt REST APIs are developed for handling CRUDN (Create, Retrieve,
Update, Delete and Notification) operations for oneM2M resources specified in oneM2M standard.
The Mobius-yt REST APIs cover guide for functionalities of devices(AE) registration, data management for the
registered AE, device management, resources CRUD management, subscription/notification, data and device
discovery etc. The current APIs will be maintained to reflect updates to existing and new oneM2M Common
Service Functions (CSFs) functionalities in oneM2M Release1.
The Mobius-yt REST APIs are initially developed for supporting HTTP and MQTT protocol binding. In current
user manual, we only provide guide for HTTP protocol binding as an example while guide for MQTT protocol
binding will be provided in the future. oneM2M standard is specified to use short name to represent oneM2M
resource and attribute primitives while protocol-dependent message transported on wire can be represented in
serializations such as XML, JSON or CBOR etc.
In previous version of Mobius-yt user manual, we use XML as content type of HTTP body while in current version
of Mobius-yt user manual, we prefer to use JSON serialization for HTTP message representations.
X-M2M-Origin: The X-M2M-Origin header is mapped to the field value of From attribute of request
and response primitive and vice versa, if applicable, and it is assigned by the Originator of the request
(e.g. AE or CSE), that is, assigned with the entity ID (AE-ID or CSE-ID) of http request originator. In
case that AE has no assigned entity ID before registration, a temporary* field value is used to send HTTP
requests, and once the entity is registered successfully to Mobius-YT, the entity will receive a formal
entity ID which is used for request originator authentication for accessing specific resources following
defined access control rules.
In CSE case, the entity ID i.e. CSE-ID starts with a slash ‘/’ while
In AE case, the entity ID i.e. AE-ID staring with an uppercase letter ‘S’ or ‘C’ and followed by any
combination of number and English letters, indicating the entity ID is assigned by service-provider
or CSE, respectively.
Examples:
#AE registration case:
X-M2M-Origin: S
X-M2M-Origin: S0.2.481.1.1.232466
Page-6
Mobius-Yellow Turtle REST APIs
X-M2M-Origin: C
X-M2M-Origin: C0.2.481.1.1.232466
X-M2M-RI: The M2M-Request-ID tracks a request initiated by an AE over the Mca reference point, or
a CSE over the Mcc reference point, if applicable, end to end. It is also included in the response to
indicate the corresponding request. A unique value has to be set to X-M2M-RI header.
Examples:
X-M2M-RI: req12345
Accept: The Originator may use the Accept header to indicate in which media type (i.e. content type
parameter) the originator prefers to receive the response. The latest version of Mobius-yt supports both
XML and JSON content type.
Examples:
Accept: application/xml
Accept: application/json
Content-Type: Any HTTP request or response containing message-body has to include Content-type
header which has to be set to either ”application/xml”,
“application/json”, ”application/vnd.onem2m-res+xml”, or
“application/vnd.onem2m-res+json”.
The Hosting CSE will send response body message which is represented in media type specified in the
Content-Type header field included in the request message if any. The Content-Type header has to be
included both in Create and Update of HTTP request.
The Resource-Type (short for rt) primitive parameter is only present in Create request and the value of Resource-
Type has to be appended to the Content-type header value of the corresponding request message in the form
ty=RESOURCE-TYPE_VALUE, separated by a semicolon character (;). A valid Content-Type header in this
case looks e.g. as follows:
Examples:
For AE Create request case: Content-Type: application/vnd.onem2m-res+xml; ty=2
For Container Create request case: Content-Type: application/vnd.onem2m-res+xml; ty=3
For any resource Update request case: Content-Type: application/vnd.onem2m-res+xml
Page-7
Mobius-Yellow Turtle REST APIs
Page-8
Mobius-Yellow Turtle REST APIs
Page-9
Mobius-Yellow Turtle REST APIs
Page-10
Mobius-Yellow Turtle REST APIs
Page-11
Mobius-Yellow Turtle REST APIs
Page-12
Mobius-Yellow Turtle REST APIs
Page-13
Mobius-Yellow Turtle REST APIs
Page-14
Mobius-Yellow Turtle REST APIs
2. OPEN APIs
2.1. API Outline
Table 2.1-1 A summary of Mobius-YT open APIs
Page-15
Mobius-Yellow Turtle REST APIs
NP (Not Present): NP mark indicates attributes that don’t necessarily be present in the resource
representation for the corresponding request via API.
Page-16
Mobius-Yellow Turtle REST APIs
M (Mandatory): M mark indicates attributes shall be present in the resource representation either for
the corresponding request via API or the responses provided by the specific IoT platform.
O (Optional): O mark indicates attributes that are allowed to be present in the resource representation
for the corresponding request for API but will not affect the request result if absent.
2) Preferences
APreferences applied through the current API are listed as following:
A resultContent attribute is used as a query string to manage user preference on the type of response
content. If the reultContent is absent in the request URL, the default value 1(attributes) is applied to
indicate the response for a corresponding request is composed of attributes of the requested resource.
More about resultContent parameter is listed on clause 0.
All resources and attributes present in the request API are represented by their corresponding short name,
which is defined by oneM2M TS-0004. More details for the short names, please refer to clause 2.2.10.
1) API-CB-C
2) API-CB-R
The <CSEBase>resource supports retrieve operation via API following generic procedures specified
in oneM2M TS-0001.
Interface ID API-CB-R
Interface Name CSEBase retrieve with resultContent set to 1 (attributes)
Target Resource Requested <CSEBase> resource
The interface is used to receive the retrieve request for <CSEBase> resource in Mobius-
YT and respond the request originator with the resource information of the CSEBase.
① Resource Structure
Interface
Description mobius-yt
② Call Flow
Page-17
Mobius-Yellow Turtle REST APIs
{
"m2m:cb": {
"ty": 5,
"ct": "20161011T064008",
"ri": "/mobius-yt",
"rn": "mobius-yt",
"lbl": [
"mobius-yt"
],
"lt": "20161011T064008",
"cst": 1,
"csi": "/mobius-yt",
"srt": [
1,
2,
3,
4,
10,
16,
23,
24,
25,
26
],
"poa": [
"http://192.168.119.1:7579"
]
}
Page-18
Mobius-Yellow Turtle REST APIs
3) API-CB-U
4) API-CB-D
For example, when CSE1 (Registree CSE) registers with CSE2 (Registrar CSE), there will be two
<remoteCSE> resources created: one in CSE1: <CSEBase1>/<remoteCSE2> and one in CSE2:
<CSEBase2>/<remoteCSE1>. Note that the creation of two <remoteCSE> resources located in
<CSEBase1> and <CSEBase2>, respectively, does not imply mutual registration (i.e.,
<CSEBase1>/<remoteCSE2> does not mean CSE2 registered with CSE1).
The <remoteCSE> resource contains a group of universal attributes applied for all oneM2M resource
primitives and a group of specific resources applied for only <remoteCSE> resource itself, shown as
Table 2.2.3- 1 and Table 2.2.3-2. Table 2.2.3-2 also shows mandatory attributes (with M mark)
required to be present while using API, as well as optional attributes (with O mark) that are not
necessarily present and those attributes (with NP mark) that should not be present in resource request
representation.
Taking a remote light control scenario at home as an example, the home gateway can be modelled as a
MN-CSE registered as a <remoteCSE> to enable the communication of local light bulbs with outside
of home network. Any light bulb to be connected to the home gateway can be registered as <AE> as a
child resource of <remoteCSE>.
Page-19
Mobius-Yellow Turtle REST APIs
1) API-CSR-C
Interface ID API-CSR-C-01
Interface Name remoteCSE creation with resultContent set to 1 (attributes)
Target Resource <CSEBase> resource of the requested <remoteCSE> resource
The interface is used to send a <remoteCSE> create request attached with resultContent
set to 1 to the Mobius-YT CSEBase and receive a successful <remoteCSE> creation
response including the created resource information of <remoteCSE> for the
<remoteCSE> create request.
Note that mandatory attributes for creation of the <remoteCSE> are highlighted in create
request.
① Resource Structure will look like as below when the <remoteCSE> resource is
created successfully under mobius-yt CSEBase.
Mobius-yt
ncube
② Call Flow between a CSE originator and its hosting CSE is shown as below:
Interface
Description
CSE Registree Mobius-YT
Page-20
Mobius-Yellow Turtle REST APIs
{
"m2m:csr":
{
"csi": "0.2.481.1.0001.001.000111",
"cb": "//myoperator.com/ncube",
"rr": true,
"rn": "ncube"
}
}
{
"m2m:csr": {
"rn": "ncube",
"ty": 16,
"pi": "/mobius-yt",
"ri": "/mobius-yt/16-20161219063217637fQdb",
"ct": "20161219T063217",
"et": "20171219T063217",
"lt": "20161219T063217",
"cb": "//myoperator.com/ncube",
"csi": "0.2.481.1.0001.001.000111",
"rr": true,
"cst": 1
}
}
Interface ID API-CSR-C-02
Interface Name remoteCSECreate with resultContent set to 0 (nothing)
Target Resource <remoteCSE> resource
The interface is used to send a <remoteCSE> create request attached with resultContent
set to 0 to the Mobius-YT CSEBase and receive a successful <remoteCSE> creation
response without containing any data about the created <remoteCSE> resource.
Interface Note that mandatory attributes for creation of the <remoteCSE> are highlighted in create
Description request.
① Resource Structure will look like as below when the <remoteCSE> resource is
created successfully under mobius-yt CSEBase.
Page-21
Mobius-Yellow Turtle REST APIs
Mobius-yt
ncube
② Call Flow between a CSE originator and its hosting CSE is shown as below:
{
"m2m:csr":
{
"csi": "0.2.481.1.0001.001.000111",
"cb": "//myoperator.com/ncube",
"rr": true,
"rn": "ncube"
}
}
Interface ID API-CSR-C-03
Interface Name remoteCSECreate with resultContent set to 2 (hierarchical-address)
Page-22
Mobius-Yellow Turtle REST APIs
Note that mandatory attributes for creation of the <remoteCSE> are highlighted in create
request.
① Resource Structure will look like as below when the <remoteCSE> resource is
created successfully under mobius-yt CSEBase.
Mobius-yt
ncube
② Call Flow between a CSE originator and its hosting CSE is shown as below:
{
"m2m:csr":
{
"csi": "0.2.481.1.0001.001.000111",
"cb": "//myoperator.com/ncube",
"rr": true,
"rn": "ncube"
}
}
Page-23
Mobius-Yellow Turtle REST APIs
Content-Length: 234
Content-Location: /mobius-yt/ncube
Content-Type: application/vnd.onem2m-res+xml; ty=16
X-M2M-RI: req12345
X-M2M-RSC: 2001
{
"m2m:uri": "/mobius-yt/ncube"
}
Interface ID API-CSR-C-04
Interface Name remoteCSECreate with resultContent set to 3 (hierarchical-address+attributes)
Target Resource <remoteCSE> resource
The interface is used to send a <remoteCSE> create request attached with resultContent
set to 3 to the Mobius-YT CSEBase and receive a successful <remoteCSE> creation
response containing both the hierarchical address and attributes representation of the
created <remoteCSE> resource.
Note that mandatory attributes for creation of the <remoteCSE> are highlighted in create
request.
① Resource Structure will look like as below when the <remoteCSE> resource is
created successfully under mobius-yt CSEBase.
Mobius-yt
ncube
② Call Flow between a CSE originator and its hosting CSE is shown as below:
Page-24
Mobius-Yellow Turtle REST APIs
Content-Type: application/vnd.onem2m-res+json;ty=16
{
"m2m:csr":
{
"csi": "0.2.481.1.0001.001.000111",
"cb": "//myoperator.com/ncube",
"rr": true,
"rn": "ncube"
}
}
Interface ID API-CSR-R
Interface Name remoteCSE retrieve with resultContent set to 1 (attributes)
Target Resource Requested <remoteCSE> resource
The interface is used to send a retrieve request attached with resultContent set to 1 to the
<remoteCSE> resource that has been created before and receive a response containing
attributes of the requested <remoteCSE> resource.
① Resource Structure
Interface Mobius-yt
Description
ncube
② Call Flow between an originator and its hosting CSE is shown as below:
Note that the external entity can be a CSE or an AE which has access control right to
access to the requested <remoteCSE> resource.
Page-25
Mobius-Yellow Turtle REST APIs
{
"m2m:csr": {
"pi": "/mobius-yt",
"ty": 16,
"ct": "20161219T071000",
"ri": "/mobius-yt/ncube",
"rn": "ncube",
"lt": "20161219T071000",
"et": "20171219T071000",
"cst": 1,
"cb": "//myoperator.com/ncube",
"csi": "0.2.481.1.0001.001.000111",
"rr": true
}
}
3) API-CSR-U
Interface ID API-CSR-U-01
Interface Name remoteCSE update with resultContent set to 1 (attributes)
Target Resource Requested <remoteCSE> resource
The interface is used to send a <remoteCSE> update request attached with resultContent
Interface set to 1 to the target <remoteCSE> resource that has been created and receive a successful
Description <remoteCSE> update response containing (at least) the updated attribute(s) of the
requested <remoteCSE> resource.
Page-26
Mobius-Yellow Turtle REST APIs
① Resource Structure
Mobius-yt
ncube
② Call Flow between an originator and its hosting CSE is shown as below:
Note that the external entity can be a CSE or an AE which has access control right to
access to the requested <remoteCSE> resource.
Page-27
Mobius-Yellow Turtle REST APIs
"ri": "/mobius-yt/ncube",
"rn": "ncube",
"lt": "20161219T071000",
"et": "20171219T071000",
"cst": 1,
"cb": "//myoperator.com/ncube",
"csi": "0.2.481.1.0001.001.000111",
"rr": true,
"poa": "http://0.2.481.1.0001.001.000111"
}
}
Interface ID API-CSR-U-02
Interface Name remoteCSEUpdate with resultContent set to 0 (nothing)
Target Resource <remoteCSE> resource
The interface is used to send an update request attached with resultContent set to 0 to the
target <remoteCSE> resource that has been created before and receive a successful
<remoteCSE> update response without containing any data about the requested
<remoteCSE> resource.
① Resource Structure
Mobius-yt
ncube
② Call Flow between an originator and its hosting CSE is shown as below:
Note that the external entity can be a CSE or an AE which has access control right to
access to the requested <remoteCSE> resource.
Page-28
Mobius-Yellow Turtle REST APIs
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req21345
X-M2M-Origin: /csencube
Content-Type: application/vnd.onem2m-res+json
{
"m2m:csr": {
"poa": "http://0.2.481.1.0001.001.000111"
}
}
Interface ID API-CSR-D-01
Interface Name remoteCSE delete with resultContent set to 0 (nothing)
Target Resource Requested <remoteCSE> resource
The interface is used to send a delete request attached with resultContent set to 0 to the
target <remoteCSE> resource that has created before and receive a successful
<remoteCSE> delete response with no http response body included.
① Resource Structure
Mobius-yt
ncube
② Call Flow between an originator and its hosting CSE is shown as below:
Note that the external entity can be a CSE or an AE which has access control right to access
to the requested <remoteCSE> resource.
Page-29
Mobius-Yellow Turtle REST APIs
Interface ID API-CSR-D-02
Interface Name remoteCSEDelete with resultContent set to 1 (attributes)
Target Resource <remoteCSE> resource
The interface is used to send a delete request attached with resultContent set to 1 to the
target <remoteCSE> resource that has created before and receive a successful
<remoteCSE> delete response containing attributes of <remoteCSE> resource that has
been deleted.
① Resource Structure
Mobius-yt
ncube
② Call Flow between an originator and its hosting CSE is shown as below:
Note that the external entity can be a CSE or an AE which has access control right to access
to the requested <remoteCSE> resource.
Page-30
Mobius-Yellow Turtle REST APIs
The <AE> resource contains a group of universal attributes which are defined to be potentially
applicable for all oneM2M resource primitives and a group of specific resources applied for only <AE>
resource itself, shown as Table 2.2.4. 1 and Table 2.2.4.2. Table 2.2.4.2 also shows mandatory attributes
(with M mark) required to be included in the request message using REST API, as well as optional
attributes (with O mark) that are not necessarily present and those attributes (with NP mark) that should
not be present in resource request representation.
The <AE> resource which resides in different kind of nodes such as Application Dedicated Node,
Middle Node, Infrastructure Node etc. An Application Dedicated Node could reside in a constrained
M2M device, while a Middle Node could reside in an M2M gateway and an Infrastructure Node could
reside in an M2M Service Infrastructure. For example, in smart home scenario, light bulbs are modelled
as Application Dedicated Node which communicate with home gateway which is modelled as a Middle
Node and in resource registration phase, light bulbs can be registered as an <AE> resource.
Page-31
Mobius-Yellow Turtle REST APIs
Interface ID API-AE-C-01
Interface Name AE creation with resultContent set to 1 (attributes)
Target Resource <CSEBase> resource of the requested <AE> resource
The interface is used to send a <AE> create request attached with resultContent set to 1
to the Mobius-YT CSEBase and receive a successful <AE> creation response including
the created resource information of <AE> for the <AE> create request.
Note that mandatory attributes for creation of the <AE> are highlighted in create request.
A temperature sensor is registered to Mobius-YT platform by sending a <AE>
registration request to the Mobius-YT CSEBase.
① Resource Structure
Mobius-yt
Interface temp_sensor
Description
② Call Flow between the request originator and the hosting CSE is shown as
below:
AE create request
Page-32
Mobius-Yellow Turtle REST APIs
{
"m2m:ae":
{
"rn": "temp_sensor",
"api": "A01.com.company.tempApp1",
"rr": true
}
}
{
"m2m:ae": {
"rn": "temp_sensor",
"ty": 2,
"pi": "/mobius-yt",
"ri": "/mobius-yt/temp_sensor",
"ct": "20170103T062535",
"et": "20180103T062535",
"lt": "20170103T062535",
"api": "A01.com.company.tempApp1",
"rr": true,
"aei": "Cae201623213"
}
}
Interface ID API-AE-C-02
Interface Name AE creation with resultContent set to 0 (nothing)
Target Resource <AE> resource
The interface is used to send a <AE> create request attached with resultContent set to 0
to the Mobius-YT CSEBase and receive a successful <AE> creation response with no
Interface
http response body included.
Description
Note that mandatory attributes for creation of the <AE> are highlighted in create request.
Page-33
Mobius-Yellow Turtle REST APIs
temp_sensor
② Call Flow between the request originator and the hosting CSE is shown as
below:
AE create request
{
"m2m:ae":
{
"rn": "temp_sensor",
"api": "A01.com.company.tempApp1",
"rr": true
}
}
Interface ID API-AE-R
Page-34
Mobius-Yellow Turtle REST APIs
① Resource Structure
Mobius-yt
temp_sensor
② Call Flow between the request originator and the hosting CSE is shown as
below: Note that the external entity depicted at the below Figure is authenticated
entity that has access right to the target AE resource.
AE retrieve request
{
"m2m:ae": {
"pi": "/mobius-yt",
"ty": 2,
"ct": "20170103T063044",
"ri": "/mobius-yt/temp_sensor",
"rn": "temp_sensor",
"lt": "20170103T063044",
"et": "20180103T063044",
"api": "A01.com.company.tempApp1",
"aei": "Cae201623213",
Page-35
Mobius-Yellow Turtle REST APIs
"rr": true
}
}
3) API-AE-U
Interface ID API-AE-U-01
Interface Name AE update with ResultContent set to 1 (attributes)
Target Resource Requested <AE> resource
The interface is used to send a <AE> update request attached with resultContent set to 1
to the target <AE> resource that has been created and receive a successful <AE> update
response containing (at least) the updated attribute(s) of the requested <remoteCSE>
resource.
① Resource Structure
Mobius-yt
temp_sensor
② Call Flow
AE update request
{
"m2m:ae":
{
"poa": ["http://192.168.0.10:9090"]
}
}
Page-36
Mobius-Yellow Turtle REST APIs
HTTP/1.1 200 OK
Content-Length: 247
Content-Type: application/json
X-M2M-RI: req63435
X-M2M-RSC: 2004
{
"m2m:ae": {
"pi": "/mobius-yt",
"ty": 2,
"ct": "20170103T063044",
"ri": "/mobius-yt/temp_sensor",
"rn": "temp_sensor",
"lt": "20170103T072803",
"et": "20180103T063044",
"api": "A01.com.company.tempApp1",
"aei": "Cae201623213",
"poa": [
"http://192.168.0.10:9090"
],
"rr": true
}
}
Interface ID API-AE-U-02
Interface Name AE update with ResultContent set to 0 (nothing)
Target Resource <AE> resource
The interface is used to send a <AE> update request attached with resultContent set to 0
to the <AE> resource that has been created before and receive a successful <AE> update
response containing only the response status code.
① Resource Structure
Mobius-yt
temp_sensor
② Call Flow
Page-37
Mobius-Yellow Turtle REST APIs
Content-Type application/vnd.onem2m-res+json
{
"m2m:ae":
{
"poa": ["http://192.168.0.10:9090"]
}
}
Interface ID API-AE-D
Interface Name AE delete with ResultContent set to 0 (nothing)
Target Resource Requested <AE> resource
Page-38
Mobius-Yellow Turtle REST APIs
The interface is used to send an <AE> delete request attached with resultContent set to
0 to an <AE> resource that has been created and receive a successful <AE> delete
response with no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
② Call Flow
AE delete request
The <container> resource contains a group of universal attributes applied for all oneM2M resource
primitives and a group of specific resources applied for only <container> resource itself, shown as Table
2.2.5. 1 and Table 2.2.5.2. Table 2.2.5.2 only shows optional attributes (with O mark) that are not
necessarily present and those attributes (with NP mark) that should not be present in resource request
Page-39
Mobius-Yellow Turtle REST APIs
representation. There are no mandatory attributes required to be present when sending a create
<container> resource request, all the attributes of <container> resources will be automatically assigned
by registrar CSE during handling create <container> request.
The <container> resource can be seen as a container of a group of data instances with same
characteristics, for example, sensor measurement of temperature, humidity, illumination, CO2 etc. For
example, when a temperature sensor is modelled as application dedicated node and registered with an
<AE> resource, a <container> resource can be created under the created <AE> as its child resource to
contain temperature measurements. Note that <container> resource has no associated content and the
real data is contained in a child resource of container called <contentInstance> which will be introduced
in section 2.2.6.
Interface ID API-CNT-C-01
Interface Name Container creation with resultContent set to 2 (hierarchical address)
Target Resource <AE> resource as a parent resource of the requested <container> resource
The interface is used to send a <container> create request attached with resultContent
set to 2 under the <AE> resource and receive a successful <container> creation response
Interface including the hierarchical address representation of the created <container> resource.
Description
① Resource Structure
Page-40
Mobius-Yellow Turtle REST APIs
Mobius-yt
temp_sensor
temp_container
② Call Flow
{
"m2m:cnt":
{
"rn": "temp_container"
}
}
{
"m2m:uri": "/mobius-yt/temp_ae/temp_container"
}
Interface ID API-CNT-C-02
Interface Name Container creation with resultContent set to 3 (hierarchical address + attributes)
Page-41
Mobius-Yellow Turtle REST APIs
① Resource Structure
Mobius-yt
temp_sensor
temp_container
② Call Flow
{
"m2m:cnt":
{
"rn": "temp_container"
}
}
Page-42
Mobius-Yellow Turtle REST APIs
{
"m2m:rce": {
"m2m:cnt": {
"rn": "temp_container",
"ty": 3,
"pi": "/mobius-yt/temp_ae",
"ri": "/mobius-yt/temp_ae/temp_container",
"ct": "20170103T084247",
"et": "20180103T084247",
"lt": "20170103T084247",
"st": 0,
"mni": 9007199254740991,
"cni": 0,
"cbs": 0
},
"m2m:uri": "/mobius-yt/temp_ae/temp_container"
}
}
2) API-CNT-R
Interface ID API-CNT-R
Interface Name Container retrieve with resultContent set to 1 (attributes)
Target Resource Requested <container> resource
The interface is used to send a <container> retrieve request attached with resultContent
set to 1 to the target <container> resource that has been created and receive attributes
representation of the requested <container> resource.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
② Call Flow
Page-43
Mobius-Yellow Turtle REST APIs
Accept: application/json
X-M2M-RI: req67392
X-M2M-Origin: Cae201623213
{
"m2m:cnt": {
"pi": "/mobius-yt/temp_sensor",
"ty": 3,
"ct": "20170103T083902",
"ri": "/mobius-yt/temp_sensor/temp_container",
"rn": "temp_container",
"lt": "20170103T083902",
"et": "20180103T083902",
"st": 0,
"mni": 9007199254740991,
"cni": 0,
"cbs": 0
}
}
3) API-CNT-U
Interface ID API-CNT-U
Interface Name Container update with resultContent set to 0 (nothing)
Target Resource Requested <container> resource
Page-44
Mobius-Yellow Turtle REST APIs
The interface is used to send a <container> update request attached with resultContent set
to 0 to the target <container> resource that has been created and receive a successful
<container> update response containing only the response status code.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
② Call Flow
{
"m2m:cnt":
{
"mni": 10000,
"lbl": ["temperature repo"]
}
}
Page-45
Mobius-Yellow Turtle REST APIs
4) API-CNT-D
Interface ID API-CNT-D
Interface Name Container delete with resultContent set to 0 (nothing)
Target Resource Requested <container> resource
The interface is used to send a <container> delete request attached with resultContent set
to 0 to a target <container> resource that has been created and receive a successful
<container> delete response with no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
② Call Flow
Page-46
Mobius-Yellow Turtle REST APIs
Taking a temperature sensor device as an example, the temperature sensor is designed to collect
temperature data of environment and in this case, the real temperature data is modelled as a
<contentInstance> resource. In details, we assume both the temperature sensor is registered with <AE>
resource and a <container> resource is created under the <AE> to store temperature instances, under
this consumption, whenever the temperature data is uploaded into a central server, the temperature data
has to be denoted as a value of content attribute of <contentInstance> resource.
The <contentInstance> resource cannot be modified once created, and is able to be deleted
explicitly by an AE or may be deleted by the platform based on specific policies. If the platform has
policies to manage the <contentInstance> resource, these policies are represented by attributes
axByteSize, maxNrOfInstances and/or maxInstanceAge attributes in their parent <container> resource.
The <contentInstance> resource inheritances the same access control policies of its parent
<container> resource, and does not have its own accessControlPolicyIDs attribute.
Interface ID API-CIN-C
Interface Name contentInstance create with resultContent set to 0 (nothing)
Target Resource <container> resource as a parent resource of the requested <contentInstance> resource
The interface is used to send a <contentInstance> create request attached with
Interface
resultContent set to 0 to the target <container> resource and receive a successful
Description
<contentInstance> creation response with no http response body included.
Page-47
Mobius-Yellow Turtle REST APIs
① Resource Structure
Mobius-yt
temp_sensor
temp_container
temperature-
20170101125630
temperature-
20170101131030
② Call Flow
{
"m2m:cin":
{
"con": "20"
}
}
Page-48
Mobius-Yellow Turtle REST APIs
Interface ID API-CIN-R
Interface Name Latest contentInstance retrieve
Target Resource <latest> virtual resource of requested <container> resource
The interface is used to send a latest <contentInstance> retrieve request to the target
<container> resource that has been created and receive attributes representation of the
latest <contentInstance> resource.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
temperature-
20170101125630
temperature-
20170101131030
② Call Flow
Page-49
Mobius-Yellow Turtle REST APIs
{
"m2m:cin": {
"pi": "/mobius-yt/temp_sensor/temp_container",
"ty": 4,
"ct": "20170103T100118",
"ri": "/mobius-yt/temp_sensor/temp_container/temperature-
20170101125630",
"rn": "4-201701031001181291oza",
"lt": "20170103T100118",
"et": "20180103T100118",
"st": 4,
"mni": 10000,
"cs": 2,
"con": "20"
}
}
3) API-CIN-D
Interface ID API-CIN-D
Interface Name contentInstance delete with resultContent set to 0 (nothing)
Target Resource <latest> virtual resource of requested <container> resource
The interface is used to send a <container> delete request attached with resultContent set
to 0 to a target <container> resource that has been created and receive a successful
<container> delete response with no http response body included.
① Resource Structure
Mobius-yt
Interface temp_sensor
Description
temp_container
temperature-
20170101125630
temperature-
20170101131030
② Call Flow
Page-50
Mobius-Yellow Turtle REST APIs
The < semanticDescriptor > resource contains a group of universal attributes applied for all oneM2M
resource primitives and a group of specific resources applied for only < semanticDescriptor > resource
itself, shown as Table 2.2.7. 1 and Table 2.2.7.2. Table 2.2.7.2 also shows mandatory attributes (with M
mark) required to be present while using API, as well as optional attributes (with O mark) that are not
necessarily present and those attributes (with NP mark) that should not be present in resource request
representation.
Page-51
Mobius-Yellow Turtle REST APIs
Interface ID API-SD-C
Interface Name SemanticDescriptor create with resultContent set to 0 (nothing)
Target Resource <container> resource of the requested <semanticDescriptor> resource
The interface is used to send a <semanticDescriptor> create request attached with
resultContent set to 0 to the target <container> resource and receive a successful
<semanticDescriptor> creation response with no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
Interface
Description
semantic_describer
② Call Flow
Page-52
Mobius-Yellow Turtle REST APIs
{
"m2m:sd":
{
"rn":"semantic_describer",
"dspt": "application/rdf+json:1",
"dsr":
"PHJkZjpSREYNCPHJkZjpSREYNCPHJkZjpSREYNCPHJkZjpSREYNC4="
}
}
Interface ID API-SD-R
Interface Name SemanticDescriptor retrieve with resultContent set to 1 (attributes)
Target Resource Requested semanticDescriptor> resource
The interface is used to send a retrieve request attached with resultContent set to 1 to the
target <semanticDescriptor> resource that has been created and receive a response
Interface containing attributes of the requested <semanticDescriptor> resource.
Description
① Resource Structure
Page-53
Mobius-Yellow Turtle REST APIs
Mobius-yt
temp_sensor
temp_container
semantic_describer
② Call Flow
{
"m2m:sd": {
"pi": "/mobius-yt/temp_sensor/temp_container",
"ty": 24,
"ct": "20170104T023903",
"ri": "/mobius-
yt/temp_sensor/temp_container/semantic_describer",
"rn": "semantic_describer",
"lt": "20170104T023903",
"et": "20180104T023903",
"st": 0,
Page-54
Mobius-Yellow Turtle REST APIs
"dspt": "application/rdf+json:1"
}
}
3) API-SD-U
Interface ID API-SD-U
Interface Name SemanticDescriptor update with resultContent set to 0 (nothing)
Target
Requested <semanticDescriptor> resource
Resource
The interface is used to send a <semanticDescriptor> update request attached with
resultContent set to 0 to the target <semanticDescriptor> resource that has been created and
receive a successful <semanticDescriptor> update response with no response body.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
semantic_describer
② Call Flow
Interface
Description semanticDesriptor update request
Page-55
Mobius-Yellow Turtle REST APIs
{
"m2m:sd":
{
"or": "ontology.ref.com/semantics"
}
}
4) API-SD-D
Interface ID API-SD-D
Interface
SemanticDescriptor delete with resultContent set to 0 (nothing)
Name
Target
Requested <semanticDescriptor> resource
Resource
The interface is used to send a <semanticDescriptor> delete request attached with
resultContent set to 0 to the target <semanticDescriptor> resource that has been created and
receive a successful <semanticDescriptor> delete response with no http response body
included.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
semantic_describer
Interface
Description
② Call Flow
Page-56
Mobius-Yellow Turtle REST APIs
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
The result of a discovery request from an Originator depends upon the filter criteria (e.g. a combination
of keywords, identifiers, location and semantic information) that can limit the scope of information
returned to the Originator and is subject to access control policy allowed by M2M Service Subscription.
An Originator could be an AE or another CSE. The scope of the search could be within one CSE, or in
more than one CSE.
The discovery request indicates the address of the resource where the discovery is to be performed.
Upon receiving such request, the DIS CSF discovers, identifies, and returns the matching information
regarding discovered resources according to the filter criteria. A successful response includes the
discovered information in the representation of <aggregatedResponse>resource.
The filterUsage element of the Filter Criteria parameter does not represent a filter condition. It
indicates how the Filter Criteria parameter shall be used. If this parameter is not provided, the Retrieve
request primitive which includes this element triggers a generic retrieve operation as shown in Table 2.
2.8-1, which means when a discovery request is preferred, the filterUsage (short for fu) has to be present
and set to either ‘1’ or ‘2’ as a query string, e.g. /mobius-yt?fu=1&ty=2, together with other Filter
Criteria parameters, e.g. the resource type (short for ty).
The difference between setting filterUsage to ‘1’ and ‘2’ reflects in the representation of discovery
response, if any. When filterUsage sets to ‘1’, the response of discovery request is represented with
format of the URIList (short for uril) and all URIs of discovered resources will be listed in the response.
There is no limitation to the number of URIs of discovered resources to be returned.
While when filterUsage sets to ‘2’, the response is represented as the responsePrimitive (short for rsp)
containing attributes of the resources that match with presented filter criteria conditions. In case that the
amount of matched resources is more than the maximum number of resources that a hosting CSE could
return, the filter criteria limit is preferred to use to limit the number of resources to be returned. In
Page-57
Mobius-Yellow Turtle REST APIs
addition, filter criteria resourceType (short for ty), label (short for lbl), createdAfter (short for cra),
createdBefore (short for crb), and limit (short for lim) are supported to be used as the filter condition
for conditional resource retrieve operation.
The value of createdAfter and createdBefore filter criteria has to be DateTime string using ‘Basic
Format’ specified in ISO8601 and the timezone is interpretated as UTC timezone. More filter criteria
parameters are listed at Table 2.2.8-2.
A group of resources shown as below are created with different label values for demonstration of
discovery operations.
Page-58
Mobius-Yellow Turtle REST APIs
"ri": "/mobius-yt/temp_sensor02",
"rn": "temp_sensor02",
"lbl": [
"temp_sensor",
"sensor",
"outdoor"
],
"lt": "20170104T030802",
"et": "20180104T030802",
"api": "A01.com.company.temptApp2",
"aei": "Cae201623213",
"rr": true
}
}
AE {
"temp_sensor03" "m2m:ae": {
"pi": "/mobius-yt",
"ty": 2,
"ct": "20170104T031337",
"ri": "/mobius-yt/temp_sensor03",
"rn": "temp_sensor03",
"lbl": [
"temp_sensor",
"sensor",
"farm_indoor"
],
"lt": "20170104T031337",
"et": "20180104T031337",
"api": "A01.com.company.temptApp3",
"aei": "Cae201623213",
"rr": true
}
}
Container {
"temp_container" "m2m:cnt": {
"pi": "/mobius-yt/temp_sensor",
"ty": 3,
"ct": "20170103T092549",
"ri": "/mobius-yt/temp_sensor/temp_container",
"rn": "temp_container",
"lbl": [
"temperature_repo",
"temp",
"indoor"
],
"lt": "20170104T060156",
"et": "20180103T092549",
"st": 9,
"mni": 10000,
"cni": 1,
"cbs": 2
}
}
Container {
"temp_container02" "m2m:cnt": {
"pi": "/mobius-yt/temp_sensor",
"ty": 3,
"ct": "20170104T060227",
"ri": "/mobius-yt/temp_sensor/temp_container02",
"rn": "temp_container02",
"lbl": [
"temperature_repo",
"temp",
"outdoor"
],
"lt": "20170104T060227",
"et": "20180104T060227",
"st": 0,
"mni": 9007199254740991,
"cni": 0,
"cbs": 0
}
}
Container {
"m2m:cnt": {
Page-59
Mobius-Yellow Turtle REST APIs
1) API-DIS-ResourceType
Interface ID API-DIS-ResourceType
Interface Name Discovery with preferred resource type attribute
Target Resource oneM2M resource primitives
The interface is used to discovery resources that match with the specific resource type value.
If found, the hosting CSE sends back the hierarchical address of the matched resources.
We demonstrate to discovery <AE> and <container> resources that stored in the mobius-yt
CSEBase resource only. For other resource types, users can try it by yourselves.
① Call Flow
Page-60
Mobius-Yellow Turtle REST APIs
X-M2M-RI: 12345
X-M2M-RSC: 2000
{
"m2m:uril": "/mobius-yt/temp_sensor /mobius-yt/temp_sensor02
/mobius-yt/temp_sensor03"
}
2) API-DIS-Label
Interface ID API-DIS-Label
Interface Name Discovery with preferred Label attribute
Target Resource oneM2M Resource Primitives
The interface is used to discovery resources that match with the specific label value. If found,
the hosting CSE sends back the hierarchical address of the matched resources.
① Call Flow
④ Example -1
Request Message
GET /mobius-yt?fu=1&lbl=sensor HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req9988123
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 87
X-M2M-RI: req9988123
X-M2M-RSC: 2000
{
"m2m:uril": "/mobius-yt/temp_sensor
/mobius-yt/temp_sensor02
/mobius-yt/temp_sensor03"
}
⑤ Example -2
Request Message
Page-61
Mobius-Yellow Turtle REST APIs
{
"m2m:uril":
"/mobius-yt/temp_sensor/temp_container
/mobius-yt/temp_sensor"
}
⑥ Example -3
Request Message
GET /mobius-yt?fu=1&lbl=outdoor HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req9988125
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 79
X-M2M-RI: req9988125
X-M2M-RSC: 2000
{
"m2m:uril":
"/mobius-yt/temp_sensor/temp_container02
/mobius-yt/temp_sensor02"
}
⑦ Example -4
Request Message
GET /mobius-yt?fu=1&lbl=temp HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req9988126
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 92
X-M2M-RI: req9988126
X-M2M-RSC: 2000
{
"m2m:uril": "/mobius-yt/temp_sensor/temp_container02 /mobius-
yt/temp_sensor/temp_container"
}
Note: Multiple filter criteria conditions can also be used together in a discovery operation to
narrow the discovery scope, e.g. label and resource type are used together as the example
shows:
⑧ Example -5
Request Message
GET /mobius-yt?fu=1&lbl=indoor&ty=2 HTTP/1.1
Host: yt.iotmobius.com:7579
Page-62
Mobius-Yellow Turtle REST APIs
Accept: application/json
X-M2M-RI: req9988124
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 75
X-M2M-RI: req9988124
X-M2M-RSC: 2000
{
"m2m:uril":
"/mobius-yt/temp_sensor"
}
3) API-DIS-Limit
Interface ID API-DIS-Limit
Interface Name Discovery with preferred limit attribute
Target Resource oneM2M Resource Primitives
The interface is used to limit the number of resources to be returned as a result of discovery
operation by specifying a filter criteria parameter limit as a query string of the request URL.
Note that the parameter limit is usually used with other filter criteria parameters together,
suich as label, resource type, createAfter, and createBefore etc.
① Call Flow
④ Exmaple -1
Request Message
GET /mobius-yt/temp_sensor?fu=1&lim=2 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req123343
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 90
X-M2M-RI: req123343
X-M2M-RSC: 2000
Page-63
Mobius-Yellow Turtle REST APIs
{
"m2m:uril": "/mobius-yt/temp_sensor/time_series_02 /mobius-
yt/temp_sensor/time_series_01"
}
4) API-DIS-CreatedBefore&CreatedAfter
Interface ID API-DIS-CreatedBefore&CreatedAfter
Interface Name Discovery with preferred createdBefore and createdAfter attribute
Target Resource oneM2M Resource Primitives
The interface is used to discovery resources that match with the period of creation time
specified by the filter criteria parameter createdBefore and createdAfter. If found, the
hosting CSE sends back the hierarchical address of the matched resources.
Note that the parameter createAfter and createBefore are usually used with other filter
criteria parameters together, suich as label, resource type, and limit etc.
① Call Flow
④ Example:
Request Message
GET /mobius-yt?fu=1&crb=20170108T072322&cra=20170101T072322
HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req16664
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 416
X-M2M-RI: req16664
X-M2M-RSC: 2000
{
"m2m:uril":
"/mobius-yt/temp_sensor/time_series_02
/mobius-yt/temp_sensor/time_series_01
Page-64
Mobius-Yellow Turtle REST APIs
/mobius-yt/temp_sensor/temp_container02
/mobius-yt/temp_sensor/temp_container
/mobius-yt/temp_sensor/temp_container/4-20170106072400523Qi0b
/mobius-yt/temp_sensor/temp_container/4-201701060723586946qMc
/mobius-yt/temp_sensor/temp_container/4-20170106072357569iSEg
/mobius-yt/temp_sensor/temp_container/4-20170106072352694gA9G"
}
5) API-DIS-offset
Interface ID API-DIS-Offset
Interface Name Discovery with preferred offset attribute
Target Resource oneM2M Resource Primitives
The interface is used to discovery child resources under a specific resource and return a list
of the child resources (if any) by excluding a number of child resource whose amount is
indicated by offset field value.
The parameter offset is usually used with other filter criteria parameters together, suich as
label, resource type, and limit etc.
① Call Flow
④ Example -1
Request Message
GET /mobius-yt?fu=1&ofst=3 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req16666
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 146
X-M2M-RI: req16666
X-M2M-RSC: 2000
{
"m2m:uril":
"/mobius-yt/temp_sensor/temp_group02
Page-65
Mobius-Yellow Turtle REST APIs
/mobius-yt/temp_sensor/temp_group
/mobius-yt/temp_sensor/temp_container/4-20170104072347771tn55"
}
6) API-DIS-Level
Interface ID API-DIS-Level
Interface Name Discovery with preferred level attribute
Target Resource oneM2M Resource Primitives
The interface is used to discovery all child resources under a target parent resource with
constraint on the specific level in the resource tree and return a list of children resources if
found. For example, level field value 2 indicates the discovery request will discovery the
direct children resources of the target resource at maximum; level value set to 3 indicates
discovery until the grand-chilren resources of the target resource at maximum.
The parameter level is usually used with other filter criteria parameters together, suich as
label, resource type, offset and limit etc.
① Call Flow
④ Example -1
Request Message
GET /mobius-yt?fu=1&lvl=3 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req16676
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 416
X-M2M-RI: req16676
X-M2M-RSC: 2000
{
"m2m:uril":
"/mobius-yt/temp_sensor/time_series_02
Page-66
Mobius-Yellow Turtle REST APIs
/mobius-yt/temp_sensor/time_series_01
/mobius-yt/temp_sensor/temp_container02
/mobius-yt/temp_sensor/temp_container
/mobius-yt/temp_sensor/temp_container/4-20170106072400523Qi0b
/mobius-yt/temp_sensor/temp_container/4-201701060723586946qMc
/mobius-yt/temp_sensor/temp_container/4-20170106072357569iSEg
/mobius-yt/temp_sensor/temp_container/4-20170106072352694gA9G"
}
7) API-DIS-Multiple-Filters
Interface ID API-DIS-multiple-filters
Interface Name Discovery with multiple filter criteria parameters (label, level, limit, offset etc)
Target Resource oneM2M Resource Primitives
The interface is used to discovery resources that match with multiple filter criteria
parameters. If found, the hosting CSE sends back the hierarchical address of the matched
resources.
① Call Flow
④ Example
Request Message
GET /mobius-
yt/temp_sensor?fu=1&crb=20170108T072322&cra=20170101T072322&lbl
=temp&lvl=3&ofst=1&lim=10 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req19676
X-M2M-Origin: Cae201623213
Response Message
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 52
X-M2M-RI: req19676
X-M2M-RSC: 2000
Page-67
Mobius-Yellow Turtle REST APIs
"m2m:uril": "/mobius-yt/temp_sensor/temp_container"
}
The <subscription> resource contains a group of universal attributes applied for all oneM2M resource
primitives and a group of specific resources applied for only <container> resource itself, shown as Table
2.2.9-1 and Table 2.2.9-2. Table 2.2.9-2 shows one mandatory attribute (with M mark) needs to be
present in a create <subscription> resource request, and optional attributes (with O mark) that are not
necessarily present in a create <subscription> resource request, as well as those attributes (with NP
mark) that should not be present in resource request representation.
The Subscription and Notification (SUB) CSF provides notifications related to a subscription that is
used to track event changes on resource, i.e. update or deletion of a resource. The scope of a resource
subscription includes tracking changes of attribute(s), direct child resource(s) as well as tracking
operations on attribute(s) and direct child resource(s), but not include tracking neither changes nor
operations on attribute(s) and direct child resource(s).
A subscription to a resource is initialized by an AE or a CSE and is granted by the Hosting CSE with
access control policies. Each subscription may include notification policies that specify which, when,
and how the notifications are sent, e.g. directly to subscriber by HTTP URL or indirectly to subscriber
via MQTT broker. Subscription resource subscriber may subscribe to a single resource via a single
subscription request, or via a single subscription subscribe to multiple resources which are grouped and
represented as a single resource. Note that subscriptions to a group is made only if the subscriber is
interested in all members of the group. If a subscription to a group is made, the Group Management
Group CSF aggregates the notifications from the group members, and notifies the subscriber with the
aggregated notifications.
When AE sends a subscription request to a resource for tracking event changes on it, the subscription
request has to include information of
Page-68
Mobius-Yellow Turtle REST APIs
notifications as shown in Table 2.2.9-3. For the moment, Mobius-YT implements three notification
event types mapped to notificationEventType field value 1, 3, and 4, respectively for tracking the
notification events as following:
When a change track event is generated, the hosting CSE (notification originator) will check the
eventNotificationCriteria attribute and its sub-attribute notificationEventType of the <subscription>
resource associated with the modified resource.
The eventNotificationCriteria and notificationEventType defines the track event types following which
the corresponding notifications are sent to the resource subscriber, as shown in Table 2.2.9-3. While
notificationContentType as shown in Table 2.2.9-4 defines the type of notification content to be
contained in the notification. If notificationContentType is set to ‘2’ indicating ‘Modified Attributes’,
the notification will only include the modified attribute while set to ‘3’ indicating ‘ResourceID’, the
notification will include the resourceID of the subscribed-to resource, and if notificationContentType
set to either ‘1’ or not present indicating the default setting of “All Attributes”, the notification will
include all attributes of the subscribed-to resource.
The notificationEventCat attribute (notification policy) indicates an event category of the subscription
that shall be included in the notification request to be able for the Notification Target to correctly handle
the notification. If the notificationEventCat attribute is set, the Notify request primitive will employ the
Event Category parameter as given in the notificationEventCat attribute. If the latestNotify attribute is
set, the subscription resource hosting CSE will assign Event Category parameter of value 'latest' of the
notifications generated pertaining to the subscription created.
If the <subscription> resource associated with the modified resource includes a <notificationSchedule>
child resource, the hosting CSE will check the time periods given in the the scheduleElement attribute
of the <notificationSchedule> child resource. Also, the hosting CSE has to check the reachability
schedule associated with the Receiver by exploring its <schedule> resource. If reachability schedules
are not present in a node, then that Entity is considered to be always reachable.
Regarding the pendingNotification attribute, if it is set to ‘sendLatest’, the subscription resource hosting
CSE will cache the most recent Notify request and set the Event Category to value of ‘latest’ and send
the latest notification to the resource subscriber following notification schedules, while if it is set to
‘sendAllPending’, the subscription resource hosting CSE will cache all the Notify request. If
pendingNotification attribute is not present, the hosting CSE will discard the corresponding Notify
requests.
oneM2M specification defines rules for the notification URL format as following:
The notificationURI attribute is defined as a list of URIs representing entities that is reachable by a
CSE (the Hosting CSE) to send notifications to them. The URI needs to be formulated to either one of
the following formats:
Page-69
Mobius-Yellow Turtle REST APIs
Besides receiving notifications through the accessible information defined in attributes such as
pointOfAccess, notificationURI, the subscriber can also use polling method by creating
<pollingChannel> resource under the subscribed-to resource to receive the notification information.
In case the subscriber is not reachable, attribute requestReachability has to set to Boolean FALSE to
indicate it is not reachablility by other entities.
For a group-related subscription, the group hosting CSE needs to configure the
notificationForwardingURI of a fanout subscription request with the configured notificationURI of the
original subscription request. The group hosting CSE also has to configure the notificationURI of the
fanout subscription request with a Resource-ID specified by the group Hosting CSE.
Regarding the format of notification URI through which the subscribed-to resource hosting CSE is able
to send notifications to the resource subscriber directly or indirectly, the Mobius-YT platform supports
two formats of notification URI compliant to HTTP and MQTT protocol, respectively.
In HTTP case, the subscribed-to hosting CSE sends directly notifications to the resource subscriber (e.g
AE or CSE) using the notificationURI attribute value with assumption that the resource subscriber sets
requestReachability attribute to BOOLEAN value TRUE to indicate its reachability by other entities.
While MQTT protocol is based on the principle of publishing messages and subscribing to Topics to
implement the indirect notification to Topics subscribers. MQTT supports multiple clients can connect
to a same MQTT broker and subscribe to Topics which they are interested in. Each client is able to
connect to the MQTT broker and publish messages associated with a topic to the MQTT broker then
the MQTT broker delivers (publishes) the published message to corresponding clients that have
subscribed to that topic. In other words, different clients can subscribe to one same topic and in this
case, when there is any (authenticated) client publishes messages to that topic, other clients which have
subscribed to this topic can receive notifications from the MQTT broker.
Entities that implement MQTT client libraries can communicate with each other through MQTT
protocol. In fact, the request and response are done by using SUBSCRIBE and PUBLISH method
associated with specific Topics. OneM2M MQTT protocol binding defines the format of Topics for
requestPrimitives and responsePrimitives, respectively as following:
Page-70
Mobius-Yellow Turtle REST APIs
/oneM2M/req/<originator>/<receiver>/<serialization-type> and
/oneM2M/resp/<originator>/<receiver>/<serialization-type>
Where <originator> and <receiver> indicate the entity ID of the request originator and the
correspoinding request receiver, e.g. in <container> resource creation request case, the originator can
be a AE while the receiver is the hosting CSE. Both the <originator> and <receiver> need to be
formulated as SP-relative-AE-ID or SP-relative-CSE-ID with omitting any leading slash “/” character.
In case the entity ID is AE case, any slash “/” character embedded in the AE-ID has to be replaced with
“:” character. The <serialization-type> field indicates the serialization type that is used for the request
and response, i.e. JSON, XML or CBOR etc.
For any entity using MQTT protocol, they have to subscribe to Topics stored in MQTT server in order
receive any requests target to themselves as well as receive responses for the requests that are initialized
by themselves. Therefore, any entities (AE and CSE) have to subscribe to two Topics after connecting
with MQTT server as following:
/oneM2M/req/+/<SP-relative-AE-ID>/# and
/oneM2M/resp/<SP-relative-AE-ID>/+/#
Or
/oneM2M/req/+/<SP-relative-CSE-ID>/# and
/oneM2M/resp/<SP-relative-CSE-ID>/+/#
Where the “+” character in the Topics is wildcard to indicate the current entity can receive any message
coming from any entity with target to the current entity and “#” character indicates any serialization
type such as XML, JSON, or CBOR etc.
After subscribe to Topics, the entity can publish any message associated with a Topic specifying the
originator and receiver to the MQTT server then MQTT server will distribute the message according to
the Topic included in the message to entites that has subscribed to that Topic.
For a complete requestPrimitive using MQTT protocol, the requestPrimitive has to contain mandatory
request parameters such as operation, from, to, primtiveContent (for CREATE and UPDATE operation)
etc. All information is included in the MQTT request payload. For details, please refer to oenM2M
MQTT protocol binding specification.
Page-71
Mobius-Yellow Turtle REST APIs
Interface ID API-SUB-C
Interface Name Subscription create with resultContent set to 0 (nothing)
Target Resource <container> resource as parent resource of the requested <subscription> resource
The interface is used to send a <subscription> create request attached with resultContent
set to 0 to the target <container> resource and receive a successful <subscription> creation
response with no http response body included. The originator is the AE-ID of an
Interface authenticated AE who has access control right to create <subscription> resource under the
Description <container>.
① Resource Structure
Page-72
Mobius-Yellow Turtle REST APIs
Mobius-yt
temp_sensor
temp_container
sub_monitor
② Call Flow
AE Mobius-YT
⑤ Assumption
In this example, when AE sends a <subsription> create request under the <container>
resource, the notificationEventType (short for net) is set to a set of value {1, 3, 4} indicating
whenever there are changes to either the update to the attribtues of subscribed-to
<container> resource, or create/delete of a direct child of the subscribed-to <container>
resource. Note that Mobius-YT only implements the track on these three event types.
In addition, attribute notificationContentType (short for nct) is set to value 2 indicating only
modified attributes will be contained in the notification request message. Attribute
pendingNotification is set to value 1 indicating only sending latest pending notifications to
the subscriber.
Page-73
Mobius-Yellow Turtle REST APIs
{
"m2m:sub":
{
"rn": "sub_monitor",
"enc": {
"net": [1, 3, 4]
},
"nu":["mqtt://iot.broker.org/S0.2.481.1.20160326004729784"],
"nct": 2,
"pn": 1
}
}
Interface ID API-SUB-R-APP
Interface Name Subscription retrieve for application monitoring with resultContent set to 1 (attributes)
Target Resource <subscription> resource
The interface is used to retrieve the <subscription> resource sub_monitor in <container>
cont_status and respond the request originator with the requested <subscription> resource
information. The originator can be any authenticated AE or CSE who has access control
right to retrieve <subscription> resource sub_monitor from <container> cont_status.
① Resource Structure
Mobius-yt
temp_sensor
Interface temp_container
Description
sub_monitor
temperature-20170101125630
temperature-20170101125630
temp_controller
sub_control
② Call Flow
Page-74
Mobius-Yellow Turtle REST APIs
AE Mobius-YT
{
"m2m:sub": {
"pi": "/mobius-yt/temp_sensor/temp_container",
"ty": 23,
"ct": "20170105T025047",
"ri": "/mobius-yt/temp_sensor/temp_container/sub_monitor",
"rn": "sub_monitor",
"lt": "20170105T025047",
"et": "20180105T025047",
"st": 0,
"enc": {
"net": [
1,
3,
4
]
},
"nu": [
"mqtt://203.253.128.151/S0.2.481.1.20160326004729784"
],
"pn": 1,
"nct": 2
}
}
3) API-SUB-U
Interface ID API-SUB-U-APP
Page-75
Mobius-Yellow Turtle REST APIs
Interface Name Subscription update for application monitoring with resultContent set to 0 (nothing)
Target Resource <subscription> resource
The interface is used to update the attribute(s) of <subscription> resource sub_monitor
under <container>resource cont_status and respond the request originator with the
updated <subscription> resource information. The originator can be any authenticated
AE or CSE who has access control right to update <subscription> resource sub_monitor.
① Resource Structure
Mobius-yt
temp_sensor
temp_container
sub_monitor
temperature-20170101125630
temperature-20170101125630
temp_controller
sub_control
② Call Flow
AE Mobius-YT
Interface
Description
Subscription update request
Request message:
PUT /mobius-yt/temp_sensor/temp_container/sub_monitor?rcn=0
HTTP/1.1
Page-76
Mobius-Yellow Turtle REST APIs
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req109239
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json
{
"m2m:sub":
{
"pn": 2
}
}
4) API-SUB-D
Interface ID API-SUB-D
Interface Name Subscription delete for application monitoring with resultContent set to 0 (nothing)
Target Resource <subscription> resource
The interface is used to send a <subscription> sub_monitor delete request with the
resultContent set to 0 to the target <container>resource temp_container and receive a
notification request containing the deleted <subscription> resource information. The
originator can be any authenticated AE or CSE who has access control right to delete
<subscription> resource sub_monitor.
① Resource Structure
Mobius-yt
temp_sensor
Interface
Description temp_container
sub_monitor
temperature-20170101125630
temperature-20170101125630
temp_controller
sub_control
② Call Flow
Page-77
Mobius-Yellow Turtle REST APIs
AE Mobius-YT
Page-78
Mobius-Yellow Turtle REST APIs
Mobius-yt
temp_sensor
temp_container
sub_monitor
temperature-20170101125630
temperature-20170101125630
temp_controller
sub_control
In device controlling use case, when the authenticated user sends a control command to the target device
through sending a creation request of a <contentInstance> resource to the <container> temp_controller
with control command value included in primitiveContent attribute, the <container> subscriber (i.e. the
target device) will receive notification from the subscribed-to <container> resource hosting CSE and
then be actuated.
While in device monitoring use case, any authenticated user subscribes to <container> temp_container
through a smart application and when there are any <contentInstance> resource created under
<container> temp_container, the authenticated user will get notified with the created direct child
resource through the smart application.
Each use case introduces the tracking notification events when either the subscribe-to-resource is
updated, the child resource of the subscribed-to-resource is created, or the child resource of the
subscribed-to-resource is deleted.
Secenario I: Notification-for-update-of-subscribed-to-resource
Page-79
Mobius-Yellow Turtle REST APIs
Mobius-yt
temp_sensor
temp_container
sub_monitor01
temperature-20170101125630
temperature-20170101125630
temp_controller
sub_control
② Call Flow
IoT application
Hosting CSE AE
(subscriber)
Subscribe to
the container resource
Authenticated
User Update attributes of
Resource created response
the subscribed-to-resource
Resource updated response
Notification to subscriber
ACK
① Call flow
AE (IoT-
Mobius-YT
application-A)
Procedures Authenticated
User
Subscription create request
Page-80
Mobius-Yellow Turtle REST APIs
④ Assumption
In the <subsription> create request, attribute notificationEventType (short for net) is set to
a value {1} indicating whenever there are update to the subscribed-to <container> resource,
a notification will be triggered. Attribute notificationURL is set to field value of
"mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729784"
where broker IP iot.ocean.org/mbroker and AE-ID
S0.2.481.1.20160326004729784 is used.
In addition, attribute notificationContentType (short for nct) is set to value 2 indicating only
modified attributes will be contained in the notification request message. Attribute
pendingNotification is set to value 1 indicating only sending latest pending notifications to
the subscriber.
{
"m2m:sub":
{
"rn": "sub_monitor01",
"enc": {
"net": [1]
},
"nu":["mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729
784"],
"nct": 2,
"pn": 1
}
}
{
"m2m:sub": {
"pi": "/mobius-yt/temp_sensor/temp_container",
"ty": 23,
"ct": "20170105T025047",
"ri": "/mobius-yt/temp_sensor/temp_container/sub_monitor01",
"rn": "sub_monitor01",
"lt": "20170105T025047",
"et": "20180105T025047",
Page-81
Mobius-Yellow Turtle REST APIs
"st": 0,
"enc": {
"net": [1]
},
"nu": [
"mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729784"
],
"pn": 1,
"nct": 2
}
}
① Call flow
AE (IoT-
Mobius-YT
application-B)
Request message:
PUT /mobius-yt/temp_sensor/temp_container?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req109239
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json
{
"m2m:cnt":
{
"mni": 200000,
"lbl": ["resource-monitoring"]
}
}
Response Message
Page-82
Mobius-Yellow Turtle REST APIs
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: req109239
X-M2M-RSC: 2004
The hosting CSE sends notification request to the subscriber and the notification request
message is formulated to MQTT request packet sent from entity (originator) mobius-yt
to entity (receiver) S0.2.481.1.20160326004729784. When the entity
S0.2.481.1.20160326004729784 succesfully receives the notification message, it
will respond with an acknowledgement.
① Call flow
Notification to the
resource subscriber
Authenticated
User
ACK
Page-83
Mobius-Yellow Turtle REST APIs
"sur":"S0.2.481.1.20160326004729784"
}
}
Response message
Entity S0.2.481.1.20160326004729784 PUBLISH a response message associated with
the Topic (as below) which specifies the target entity mobius-yt:
/oneM2M/resp/mobius-yt/S0.2.481.1.20160326004729784/json
{
"m2m:rsp":
{
"rsc":2000,
"fr": "S0.2.481.1.20160326004729784",
"rqi":"rqi-20160414063014594jn3d"
}
}
Secenario II: Notification-for-child-creation-of-subscribed-to-resource
Mobius-yt
temp_sensor
temp_container
sub_monitor02
temperature-20170101125630
temperature-20170101125630
temp_controller
sub_control
Page-84
Mobius-Yellow Turtle REST APIs
- The hosting CSE sends a notification to the subscriber and the subscriber sends
back an acknowledgement.
① Call flow
AE (IoT-
Mobius-YT
application-A)
④ Assumption
In the <subsription> create request, attribute notificationEventType (short for net) is set to
a value {3} indicating whenever there is any child resource got created under the
Procedures subscribed-to <container> resource, a notification will be triggered. Attribute
notificationURL is set to field value of
"mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729795"
where broker IP iot.ocean.org/mbroker and AE-ID
S0.2.481.1.20160326004729795 is used.
In addition, attribute notificationContentType (short for nct) is set to value 2 indicating only
modified attributes will be contained in the notification request message. Attribute
pendingNotification is set to value 1 indicating only sending latest pending notifications to
the subscriber.
{
"m2m:sub":
{
"rn": "sub_monitor02",
"enc": {
"net": [3]
},
"nu":["mqtt://iot.ocean.org/mbroker/S0.2.481.1.201603260047297
95"],
"nct": 2,
Page-85
Mobius-Yellow Turtle REST APIs
"pn": 1
}
}
{
"m2m:sub": {
"pi": "/mobius-yt/temp_sensor/temp_container",
"ty": 23,
"ct": "20170105T025047",
"ri": "/mobius-yt/temp_sensor/temp_container/sub_monitor02",
"rn": "sub_monitor02",
"lt": "20170105T025047",
"et": "20180105T025047",
"st": 0,
"enc": {
"net": [3]
},
"nu": [
"mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729795"
],
"pn": 1,
"nct": 2
}
}
① Call flow
AE (IoT-
Mobius-YT
application-B)
Page-86
Mobius-Yellow Turtle REST APIs
Request message:
POST /mobius-yt/temp_sensor/temp_container?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req109233
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json?ty=4
{
"m2m:cin":
{
"con":"35"
}
}
Response Message
HTTP/1.1 201 CREATED
Content-Length: 0
Content-Type: application/json
Content-Location: /mobius-
yt/temp_sensor/temp_container/temperature-20170111145630
X-M2M-RI: req109233
X-M2M-RSC: 2001
The hosting CSE sends notification request to the subscriber and the notification request
message is formulated to MQTT request packet sent from entity (originator) mobius-yt
to entity (receiver) S0.2.481.1.20160326004729795. When the entity
S0.2.481.1.20160326004729795 succesfully receives the notification message, it
will respond with an acknowledgement.
① Call flow
Notification to the
resource subscriber
Authenticated
User
ACK
Page-87
Mobius-Yellow Turtle REST APIs
The hosting CSE PUBLISH the notification request message in the payload associated with Topic
/oneM2M/req/mobius-yt/S0.2.481.1.20160326004729795/json
{
"m2m:sgn":
{
"nev":
{
"rep":
{
"m2m:cin":
{
"con":"35"
}
}
},
"sur":"S0.2.481.1.20160326004729795"
}
}
Response message
Entity S0.2.481.1.20160326004729795 PUBLISH a response message associated with
the Topic (as below) which specifies the target entity mobius-yt:
/oneM2M/resp/mobius-yt/S0.2.481.1.20160326004729795/json
{
"m2m:rsp":
{
"rsc":2000,
"fr": "S0.2.481.1.20160326004729795",
"rqi":"rqi-20160414063014594jn3d"
}
}
Mobius-yt
temp_sensor
temp_container
Description sub_monitor03
temperature-20170101125630
temperature-20170101125630
temp_controller
sub_control
② Call Flow
Page-88
Mobius-Yellow Turtle REST APIs
IoT application
Hosting CSE AE
(subscriber)
Subscribe to
the container resource
Authenticated Child resource delete
User
Resource created response request to
the subscribed-to-resource
Resource deleted response
Notification to subscriber
ACK
① Call flow
AE (IoT-
Mobius-YT
application-B)
④ Assumption
In the <subsription> create request, attribute notificationEventType (short for net) is set to
a value {4} indicating whenever there is any child resource got deleted under the
subscribed-to <container> resource, a notification will be triggered. Attribute
notificationURL is set to field value of
"mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729982"
where broker IP iot.ocean.org/mbroker and AE-ID
S0.2.481.1.20160326004729982 is used.
In addition, attribute notificationContentType (short for nct) is set to value 2 indicating only
modified attributes will be contained in the notification request message. Attribute
Page-89
Mobius-Yellow Turtle REST APIs
{
"m2m:sub":
{
"rn": "sub_monitor03",
"enc": {
"net": [4]
},
"nu":["mqtt://iot.ocean.org/mbroker/S0.2.481.1.201603260047299
82"],
"nct": 2,
"pn": 1
}
}
{
"m2m:sub": {
"pi": "/mobius-yt/temp_sensor/temp_container",
"ty": 23,
"ct": "20170105T025047",
"ri": "/mobius-yt/temp_sensor/temp_container/sub_monitor03",
"rn": "sub_monitor03",
"lt": "20170105T025047",
"et": "20180105T025047",
"st": 0,
"enc": {
"net": [4]
},
"nu": [
"mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729982"
],
"pn": 1,
"nct": 2
}
}
① Call flow
Page-90
Mobius-Yellow Turtle REST APIs
AE (IoT-
Mobius-YT
application-B)
Request message:
DELETE /mobius-yt/temp_sensor/temp_container/oldest?rcn=0
HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req109233
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json
Response Message
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: req109233
X-M2M-RSC: 2002(DELETED)
The hosting CSE sends notification request to the subscriber and the notification request
message is formulated to MQTT request packet sent from entity (originator) mobius-yt
to entity (receiver) S0.2.481.1.20160326004729982. When the entity
S0.2.481.1.20160326004729982 succesfully receives the notification message, it
will respond with an acknowledgement.
① Call flow
Page-91
Mobius-Yellow Turtle REST APIs
Notification to the
resource subscriber
Authenticated
User
ACK
{
"m2m:rsp":
{
"rsc":2000,
"fr": "S0.2.481.1.20160326004729982",
"rqi":"rqi-20160414063014594jn3d"
}
Page-92
Mobius-Yellow Turtle REST APIs
Secenario I: Notification-for-device-control
Mobius-yt
temp_sensor
temp_controller
sub_control
ctrl_cmd01
② Call Flow
Target physical IoT application AE
Hosting CSE
device (subscriber)
Description Subscribe to
the container resource
Authenticated
User Resource created response Child resource creation
under the
subscribe-to-resource
Resource created
Notification with control command response
Page-93
Mobius-Yellow Turtle REST APIs
AE (IoT-
Mobius-YT
application-A)
④ Assumption
In the <subsription> create request, attribute notificationEventType (short for net) is set to
a value {1, 3, 4 } indicating whenever there is any child resource got created/deleted under
the subscribed-to <container> resource, or any successful update to the subscribed-to-
<container>, a notification will be triggered.
Attribute notificationURL is set to field value of
"mqtt://iot.ocean.org/mbroker/S1.352.7.0.20170111014729892"
where broker IP iot.ocean.org/mbroker and AE-ID of the target physical device
S1.352.7.0.20170111014729892 is used.
In addition, attribute notificationContentType (short for nct) is set to value 2 indicating only
modified attributes will be contained in the notification request message. Attribute
pendingNotification is set to value 1 indicating only sending latest pending notifications to
the subscriber.
{
"m2m:sub":
{
"rn": "sub_control",
"enc": {
"net": [1,3,4]
},
"nu":["mqtt://iot.ocean.org/mbroker/S1.352.7.0.201701110147298
92"],
"nct": 2,
"pn": 1
}
}
Page-94
Mobius-Yellow Turtle REST APIs
Content-Length: 0
Content-Location: /mobius-
yt/temp_sensor/temp_container/sub_monitor
Content-Type: application/json
X-M2M-RI: req14335
X-M2M-RSC: 2001
{
"m2m:sub": {
"pi": "/mobius-yt/temp_sensor/temp_controller",
"ty": 23,
"ct": "20170106T025047",
"ri": "/mobius-yt/temp_sensor/temp_controller/sub_control",
"rn": "sub_control",
"lt": "20170106T025047",
"et": "20180106T025047",
"st": 0,
"enc": {
"net": [1,3,4]
},
"nu": [
"mqtt://iot.ocean.org/mbroker/S1.352.7.0.20170111014729892"
],
"pn": 1,
"nct": 2
}
}
① Call flow
AE (IoT-
Mobius-YT
application-B)
Request message:
POST /mobius-yt/temp_sensor/temp_controller?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req109223
Page-95
Mobius-Yellow Turtle REST APIs
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json?ty=4
{
"m2m:cin":
{
"con":"onStart"
}
}
Response Message
HTTP/1.1 201 CREATED
Content-Length: 0
Content-Type: application/json
Content-Location: /mobius-
yt/temp_sensor/temp_controller/ctrl_cmd01
X-M2M-RI: req109223
X-M2M-RSC: 2001
The hosting CSE sends notification request to the subscriber and the notification request
message is formulated to MQTT request packet sent from entity (originator) mobius-yt
to entity (receiver) S1.352.7.0.20170111014729892. When the entity
S1.352.7.0.20170111014729892 succesfully receives the notification message, it
will respond with an acknowledgement.
① Call flow
Page-96
Mobius-Yellow Turtle REST APIs
{
"rep":
{
"m2m:cin":
{
"pi": "/mobius-yt/temp_sensor/temp_controller",
"ty": 4,
"ct": "20170111T100118",
"ri": "/mobius-
yt/temp_sensor/temp_controller/ctr_cmd01",
"rn": " ctr_cmd01",
"lt": "20170111T100118",
"et": "20180111T100118",
"st": 1,
"mni": 10000,
"cs": 2,
"con":"onStart"
}
}
},
"sur":"S1.352.7.0.20170111014729892"
}
}
In order to enable the management (including update and retrieve) of a group of resources through a
simple operation e.g. HTTP Post operation, oneM2M specifications also defines a virtual child resource
<fanOutPoint> to manupulate operations against group members, i.e. whenever the request is sent to
the <fanOutPoint> resource under its parent <group> resource, the request is fanned out to each member
of the <group> resource, which are indicated by the memberIDs attribute in the <group> resource, and
the corresponding responses are aggregated from each member and responded to the Originator.
For example, if a group resource containing two container resources, a <fanOutPoint> request to create
a contentInstance will result in the creation of the contentInstance resource under all the container
resources in the addressed group resource. In practice, this example can be used for remote lights control
scenario by creating a contentInstance with content attribute set to OFF (or ON) to change the light
status of a group of lights one time. Another example of using <fanOutPoint> resource is to create
<subscription> resource to group members e.g. containers. Once the <subscription> resources are
created under all group members, the Originator is able to retrieve and aggregate notifications from
those subscriptions. Note that attribute notificationForwardingURI should be contained in the
<subscription> fanOutPoint request.
Page-97
Mobius-Yellow Turtle REST APIs
The <group> resource also support to contain sub-group resources. The creation procedures for the sub-
group resources are same with its parent <group> resource.
The fanOut request to the members of sub-group resource can be implemented by specifying the request
URI to <URI of parent group resource>/fanOutPoint/fanOutPoint. Additional
relative address can also be appended to the request URI of <URI of parent group
resource>/fanOutPoint/fanOutPoint, then it would look like <URI of parent group
resource>/fanOutPoint/fanOutPoint/<relative address>.
The universal attributes of <group> resource is shown in Table 2.2.10.1 while the group resource-
specific attributes are defined in Table 2.2.10.2 as below.
Page-98
Mobius-Yellow Turtle REST APIs
Interface ID API-GRP-C
Interface Name Group create with resultContent set to 0 (nothing)
Target Resource Parent resource <AE> of the requested <group> resource
The interface is used to send a <group> create request attached with resultContent set to
0 to the target <AE> resource and receive a successful <group> creation response with
no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
temp_group
Interface
Description
② Call Flow
Page-99
Mobius-Yellow Turtle REST APIs
{
"m2m:grp" : {
"mid": [
"/mobius-yt/temp_sensor/temp_container",
"/mobius-yt/temp_sensor/temp_container02"
],
"mnm": 50,
"mt": 3,
"rn": "temp_group"
}
}
2) API-GRP-R
Interface ID API-GRP-R
Interface Name Group retrieve with resultContent set to 1 (attributes)
Target Resource Requested <group> resource
The interface is used to send a <group> create request attached with resultContent set to
0 to the target <AE> resource and receive a successful <group> creation response with
no http response body included.
① Resource Structure
Mobius-yt
Interface
Description
temp_sensor
temp_group
② Call Flow
Page-100
Mobius-Yellow Turtle REST APIs
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
{
"m2m:grp": {
"rn": "temp_group02",
"ty": 9,
"pi": "/mobius-yt/temp_sensor",
"ri": "/mobius-yt/temp_sensor/temp_group",
"ct": "20170105T071432",
"et": "20180105T071432",
"lt": "20170105T071432",
"st": 0,
"mnm": 50,
"mid": [
"/mobius-yt/temp_sensor/temp_container",
"/mobius-yt/temp_sensor/temp_container02"
],
"mt": 3,
"csy": 1,
"cnm": 2,
"mtv": true
}
}
3) API-GRP-U
Interface ID API-GRP-U
Interface Name Group update with resultContent set to 0 (nothing)
Page-101
Mobius-Yellow Turtle REST APIs
① Resource Structure
Mobius-yt
temp_sensor
temp_group
② Call Flow
{
"m2m:grp" : {
"mnm": 100,
"lbl": ["containers_group"]
}
}
Page-102
Mobius-Yellow Turtle REST APIs
4) API-GRP-D
Interface ID API-GRP-D
Interface Name Group delete with resultContent set to 0 (nothing)
Target Resource Requested <group> resource
The interface is used to send a <group> delete request attached with resultContent set to
0 to the target <group> resource that has been created and receive a successful <group>
delete response with no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
temp_group
② Call Flow
Interface
Description
③ Resource URL Information
DELETE /mobius-yt/temp_sensor/temp_group?rcn=0
Page-103
Mobius-Yellow Turtle REST APIs
The <TimeSeries> resource can be understood as similar with <container> resource in such aspect:
[1] Both are represented as a container for data instances and have no associated content and have only
attributes and child resources,
[2] Both have a group of attributes representating the limitation on the data container, such as
maxNrOfInstances, maxByteSize, maxInstanceAge as well as currentNrOfInstances and currentByteSize
etc.
[5] defines a group of resource-specific attributes representing features of time series data, such as
periodicInterval indicating the time period that the time series data is collected, missingDataCurrentNr
indicating the current number of time series data that has been missed by the data receiver etc.\
[6] <timeSeries> resource doesn’t have virtual resource <latest> and <oldest> which are defined to retrieve
the most recent created and the eldest <contentInstances> as defined in <container> resource.
A group of universal attributes defined for <timeSeries> resource is listed at Table 2.2.11-1 and resource-specific
attributes is listed at Table 2.2.11-2.
Page-104
Mobius-Yellow Turtle REST APIs
Child Resource Type Child Resource Name Multiplicity Ref. to in Resource Type
Definition
<timeSeriesInstance> [variable] 0…n [2]TS-0004 clause 7.4.39
<subscription> [variable] 0…n [2]TS-0004 clause 7.4.8
<semanticDescriptor> [variable] 0...n [2]TS-0004 clause 7.4.34
1) API-TS-C
Interface ID API-TS-C
Interface Name timeSeries create with resultContent set to 0 (nothing)
Target Resource Parent resource <AE> of the requested <timeSeries> resource
The interface is used to send a <timeSeries> create request attached with resultContent
set to 0 to the target <AE> resource and receive a successful <timeSeries> creation
Interface response with no http response body included.
Description
① Resource Structure
Page-105
Mobius-Yellow Turtle REST APIs
Mobius-yt
temp_sensor
timeSeries_cnt
② Call Flow
{
"m2m:ts":
{
"rn": "timeSeries_cnt",
"pei": 1000,
"mdd": true,
"mdt": 200
}
}
Page-106
Mobius-Yellow Turtle REST APIs
2) API-TS-R
Interface ID API-TS-R
Interface Name timeSeries retrieve with resultContent set to 1 (attributes)
Target Resource Requested <timeSeries> resource
The interface is used to send a <timeSeries> create request attached with resultContent
set to 0 to the target <AE> resource and receive a successful <timeSeries> creation
response with no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
timeSeries_cnt
② Call Flow
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Page-107
Mobius-Yellow Turtle REST APIs
HTTP/1.1 200 OK
Content-Length: 279
Content-Type: application/json
X-M2M-RI: req399325
X-M2M-RSC: 2000
{
"m2m:ts": {
"rn": "timeSeries_cnt",
"ty": 29,
"pi": "/mobius-yt/temp_sensor",
"ri": "/mobius-yt/temp_sensor/timeSeries_cnt",
"ct": "20170109T053451",
"et": "20180109T053451",
"lt": "20170109T053451",
"st": 0,
"mni": 9007199254740991,
"pei": 1000,
"mdd": true,
"mdn": 1000,
"mdc": 0,
"mdt": 200,
"cni": 0,
"cbs": 0
}
}
3) API-TS-U
Interface ID API-TS-U
Interface Name timeSeries update with resultContent set to 0 (nothing)
Target Resource Requested <timeSeries> resource
The interface is used to send a <timeSeries> update request attached with resultContent
set to 0 to the target <timeSeries> resource and receive a successful <timeSeries>
creation response with no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
Interface timeSeries_cnt
Description
② Call Flow
Page-108
Mobius-Yellow Turtle REST APIs
PUT /mobius-yt/temp_sensor/timeSeries_cnt?rcn=0
{
"m2m:ts":
{
"mdn":200
}
}
Interface ID API-TS-D
Interface Name timeSeries delete with resultContent set to 0 (nothing)
Target Resource Requested <timeSeries> resource
The interface is used to send a <timeSeries> delete request attached with resultContent set
to 0 to the target <timeSeries> resource that has been created and receive a successful
<timeSeries> delete response with no http response body included.
① Resource Structure
Mobius-yt
Interface
Description
temp_sensor
timeSeries_cnt
② Call Flow
Page-109
Mobius-Yellow Turtle REST APIs
A group of universal attributes defined for <timeSeriesInstance> resource is listed at Table 2.2.12-1 and resource-
specific attributes is listed at Table 2.2.12- 2.
Page-110
Mobius-Yellow Turtle REST APIs
Interface ID API-TSI-C
Interface Name timeSeries create with resultContent set to 0 (nothing)
Target Resource Parent resource <timeSeries> of the requested <timeSeriesInstance> resource
The interface is used to send a <timeSeriesInstance> create request attached with
resultContent set to 0 to the target <timeSeries> resource and receive a successful
<timeSeriesInstance> creation response with no http response body included.
① Resource Structure
Mobius-yt
temp_sensor
timeSeries_cnt
timeSeries_instance01
Interface
Description timeSeries_instance02
② Call Flow
Page-111
Mobius-Yellow Turtle REST APIs
{
"m2m:tsi":
{
"rn": "timeSeries_instance01",
"dgt": "20170106T152424",
"con": "30"
}
}
Interface ID API-TSI-R
Interface Name timeSeriesInstance retrieve with resultContent set to 1 (attributes)
Target Resource Requested <timeSeriesInstance> resource
The interface is used to send a <timeSeriesInstance> create request attached with
resultContent set to 0 to the target <timeSeriesInstance> resource and receive a
successful <timeSeriesInstance> creation response with no http response body included.
① Resource Structure
Mobius-yt
Interface
Description temp_sensor
timeSeries_cnt
timeSeries_instance01
timeSeries_instance02
② Call Flow
Page-112
Mobius-Yellow Turtle REST APIs
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
{
"m2m:tsi": {
"rn": "timeSeries_instance01",
"ty": 30,
"pi": "/mobius-yt/temp_sensor/timeSeries_cnt01",
"ri": "/mobius-
yt/temp_sensor/timeSeries_cnt01/timeSeries_instance01",
"ct": "20170109T022828",
"et": "20180109T022828",
"lt": "20170109T022828",
"st": 3,
"cs": 2,
"con": "30",
"dgt": "20170106T152424"
}
}
3) API-TSI-U
Interface ID API-TSI-U
Interface Name timeSeries update with resultContent set to 0 (nothing)
Target Resource Requested <timeSeriesInstance> resource
Page-113
Mobius-Yellow Turtle REST APIs
Interface
Update operation is not allowed to <timeSeriesInstance> resource.
Description
4) API-TSI-D
Interface ID API-TSI-D
Interface Name timeSeriesInstance delete with resultContent set to 0 (nothing)
Target Resource Requested <timeSeriesInstance> resource
The interface is used to send a <timeSeriesInstance> delete request attached with
resultContent set to 0 to the target <timeSeriesInstance> resource that has been created
and receive a successful <timeSeriesInstance> delete response with no http response body
included.
① Resource Structure
Mobius-yt
temp_sensor
timeSeries_cnt
timeSeries_instance01
timeSeries_instance02
② Call Flow
Interface
Response with no http response body included
Description
Page-114
Mobius-Yellow Turtle REST APIs
HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
X-M2M-RI: req979332
X-M2M-RSC: 2002
References:
oneM2M Specifications:
[1] TS-0001 Functional_Architecture
Page-115