You are on page 1of 115

REST APIs for Mobius: Yellow Turtle

APIs Guide document v2.0


Mobius-Yellow Turtle REST APIs

Copyright and Disclaimer of Liability


This document may contain technical inaccuracy or type errors, and the author does not have
any responsibility on this matter.

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.

 Anyone can contribute to improvement of the open source environment of OCEAN. If


so, the developed source code should follow the license policy of OCEAN.

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

1. Mobius OPEN REST APIs


1.1. REST APIs
This user manual provides guide for users who use REST APIs of Mobius Yellow Turtle (short for Mobius-yt)
IoT server platform for their own purposes.

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.

For more preferences, please go to clause 2.2.1.

1.2. Common HTTP Header Field Settings


A group of HTTP headers are defined in oneM2M HTTP binding specification with specific field value. These
headers are specified to be used in HTTP requests for CRUD operations as following:

 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.

The format of entity ID is specified in oneM2M standard in the way as following:

 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

#CSE registration case:


X-M2M-Origin: /4akkeakjdfq423
X-M2M-Origin: //globalm2m.org/C190XX7T

 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

1.3. oneM2M Data Types Reference


Table 1.3-1 oneM2M Simple Data Types
XSD type name Type Name Examples Description
m2m:ID Generic ID //globalm2m.org Used to represent generic IDs generated and used
within oneM2M (M2M-SP-ID)
//globalm2m.org/C190XX7 (CSE-ID)
T
//globalm2m.org/CSE1/123 (AE-ID)
A38ZZY
m2m:nodeID Node ID urn:gsma:imei:90420156- Used for Node IDs. The constraints on this type are
025763-0;svn=42 different from those on Generic IDs
(IMEI as node ID)
m2m:deviceID Device ID urn:dev:ops:012345- A Device ID identifies a device using a Universally
Set%2DTop%2DBox- Unique IDentifier (UUID). A valid hex digit
0123456789 character string of UUID and the format of the URN
is one of OPS URN, OS URN, IMEI URN, ESN
URN, or MEID URN.
m2m:externalID M2M-EXT-ID urn:gsma:imei:90420156- The External Identifier allows the Underlying
025763-0;vers=0 Network to identify the M2M Device (e.g. ASN,
MN) associated with the CSE-ID.In 3GPP case, the
accessID is mapped to External Identifier as
specified in TS 23.003.
m2m:requestID Request ID ab3f124a, CSE1/98821 Used for Request IDs. This type may include the ID
of the target CSE as well as a part that varies for
each ID
m2m:nhURI Non Hierarchical /CSE090112/ C190XX7T Used where a resourceID is required to be non-
Identifier hierarchical
m2m:acpType List of ACP Resource //IN- Used to represent a list of AccessControlPolicy
IDs CSEID.m2m.myoperator.or identifiers.
g/93405
m2m:labels list of xs:token printers networkwifi1 home A list of tokens used as keys for discovering resourc
_energy es (searching wifi connected printer from vendor
1)
m2m:triggerRecipientID Trigger Recipient 3010 Used when device triggering services are requested
Identifier from the Underlying Network, to identify an
instance of an ASN/MN-CSE on an execution
environment, to which the trigger is routed. Defined
as port number in the range 0 to 65535.
m2m:listOfM2MID List of M2M identifiers xs:list of elements of data type m2m:ID
m2m:listOfMinMax List of Time Limits 10 2560 xs:list of two xs:long values defining min and max
limits of time intervals in units of milliseconds
(value -1 representing infinite time)
m2m:backOffParameters List of Backoff 100 100 2000 Ordered sequence of 3 values of data type
Parameters xs:nonNegativeInteger representing backoffTime,
backoffTimeIncrement, maximumBackoffTime (in
units of milliseconds)
m2m:ipv4 IPv4 address string with 10.125.0.0/16,122.77.12.1 Used in m2m:accessControlRules
optional CIDR suffix
m2m:ipv6 IPv6 address string with ::/0, Fadf:ddd0::/32, Used in m2m:accessControlRules
optional CIDR suffix abcd:ffff:abb0:aaaa::/64
m2m:countryCode Country Code KR 2-character country code as defined by ISO-3166
m2m:poaList List of PointOfAccess st http://172.25.0.10:8080, list of xs:string. Each pointOfAccess entry in li
rings coap://m2m.sp.com st is represented as a string containing the unde
rlying transport protocol as well as the IP addre
ss and port (or an FQDN).
m2m:timestamp Time stamp string 20141003T112032 DateTime string of ‘Basic Format’ specified in I
SO8601. Time zone shall be interpreted as UTC
timezone.
m2m:absRelTimestamp absolute or relative ti 20141003T112032 (absolut defined as xs:union of m2m:timestamp and xs:d
me stamp string e time),or uration data types
3600000 (relative time)
m2m:typeOfContent Type of Content application/xml The media type shall be an IANA registered M
edia Types name, or an experimental Media Ty
pe ‘:’
m2m:contentInfo Content Information application/xml:2 A string consisting of a media type optionally f
ollowed by a m2m:encoding separated by ‘:’ cha
racter.
See Note-1.
m2m:eventCat Event Category 2 Either
One of the values from m2m:stdEventCats or

Page-8
Mobius-Yellow Turtle REST APIs

XSD type name Type Name Examples Description


A user-defined category in the range 100-999
m2m:eventCatWithDef Event Category with d 0 Either
efault A value from m2m:eventCat, or
The value 0 which has the special meaning “def
ault”
m2m:listOfEventCat List of (applicable) Eve 1 101 xs:list of elements of data type m2m:eventCat
nt Categories

m2m:listOfEventCatWith List of m2m:eventCat 0 1 101


Def WithDef
m2m:scheduleEntry Schedule Entry * 0-5 2,6,10 * * * * The string is used to describe a duration of ena
blement.
m2m:attributeList List of xs:NCName poa rr Used for the Content parameter of Retrieve requ
est primitives and in m2m:eventNotificationCriter
ia. Attributes represented with their short names.
m2m:serviceRoles List of SRole-IDs “01-001” (see note 2) NO Used to represent a list of SRole-IDs.
TE: This is an enumeratio
n of String value)
Note-1: the encoding in m2m:contentInfo may be omitted when the value was ''0 (plain)". But since default value of encoding
is not allowed in future releases, it is recommended not to omit the encoding.

1.4. Result Content reference


Table 1.4-1 Interpretation of ResultContent
Value Interpretation Note
0 nothing
1 attributes Default value
2 hierarchical address
3 hierarchical address and attributes
4 attributes and child resources
5 attributes and child resource references
6 child resource references
7 original resource
NOTE: See clause TS-0004 6.4.1 clause “Request message parameter data types”

1.5. Short name representation


1.5.1. Resource and specialization type short name
Table 2.2.10. 1 shows short names for corresponding resource and specialization type defined in
oneM2M standard. Parts of short names are referred to be used in the current API.

Table 1.5-1 Resource and specialization type short names

Resource Type Name Short Name


accessControlPolicy acp
accessControlPolicyAnnc acpA
AE ae
AEAnnc aeA
container cnt
containerAnnc cntA
latest la
oldest ol
contentInstance cin
contentInstanceAnnc cinA
CSEBase cb
delivery dlv

Page-9
Mobius-Yellow Turtle REST APIs

Resource Type Name Short Name


eventConfig evcg
execInstance exin
fanOutPoint fopt
group grp
groupAnnc grpA
locationPolicy lcp
locationPolicyAnnc lcpA
m2mServiceSubscriptionProfile mssp
mgmtCmd mgc
mgmtObj mgo
mgmtObjAnnc mgoA
node nod
nodeAnnc nodA
pollingChannel pch
pollingChannelURI pcu
remoteCSE csr
remoteCSEAnnc csrA
request req
schedule sch
scheduleAnnc schA
serviceSubscribedAppRule asar
serviceSubscribedNode svsn
statsCollect stcl
statsConfig stcg
subscription sub
firmware fwr
firmwareAnnc fwrA
software swr
softwareAnnc swrA
memory mem
memoryAnnc memA
areaNwkInfo ani
areaNwkInfoAnnc aniA
areaNwkDeviceInfo andi
areaNwkDeviceInfoAnnc andiA
battery bat
batteryAnnc batA
deviceInfo dvi
deviceInfoAnnc dviA
deviceCapability dvc
deviceCapabilityAnnc dvcA
reboot rbo *
rebootAnnc rboA
eventLog evl
eventLogAnnc evlA
cmdhPolicy cmp
activeCmdhPolicy acmp
cmdhDefaults cmdf
cmdhDefEcValue cmdv
cmdhEcDefParamValues cmpv
cmdhLimits cml
cmdhNetworkAccessRules cmnr
cmdhNwAccessRule cmwr
cmdhBuffer cmbf
notificationTargetMgmtPolicyRef ntpr
notificationTargetPolicy ntp
policyDeletionRules pdr
notificationTargetSelfReference ntsr
dynamicAuthorizationConsultation dac

Page-10
Mobius-Yellow Turtle REST APIs

1.5.2. Resource attribute short names


In protocol bindings resource attributes names have to be translated into short names as shown in Table
1.5-2.

Table 1.5-2 Resource attribute short names

Attribute Name Occurs in Short Name


accessControlPolicyIDs All except accessControlPolicy, contentInstance acpi
announcedAttribute accessControlPolicy, AE, container, aa
contentInstance, group, locationPolicy, mgmtObj,
node, remoteCSE, schedule
announceTo accessControlPolicy, AE, container, at
contentInstance, group, locationPolicy, mgmtObj,
node, remoteCSE, schedule
creationTime All ct
expirationTime All except contentInstance, CSEBase et
labels All (optional) lbl
lastModifiedTime All lt
Link All lnk
parentID All pi
resourceID All ri
resourceType All ty*
resourceName All rn
privileges accessControlPolicy pv
selfPrivileges accessControlPolicy pvs
App-ID AE api
AE-ID AE aei
appName AE apn
pointOfAccess AE, CSEBase, remoteCSE poa
ontologyRef AE, container, contentInstance or
nodeLink AE, CSEBase, remoteCSE nl
contentSerialization AE csz
creator container, contentInstance,eventConfig, group, cr
pollingChannel, statsCollect, statsConfig,
subscription
maxNrOfInstances container mni
maxByteSize container mbs
maxInstanceAge container mia
currentNrOfInstances container cni
currentByteSize container cbs
locationID container li
contentInfo contentInstance cnf
contentSize contentInstance cs
primitiveContent request pc*
content contentInstance con
cseType CSEBase, remoteCSE cst
CSE-ID CSEBase, remoteCSE, service SubscribedNode csi
supportedResourceType CSEBase srt
notificationCongestionPolicy CSEBase ncp
source delivery sr
target delivery, request tg
lifespan delivery ls
eventCat delivery ec*
deliveryMetaData delivery dmd
aggregatedRequest delivery arq
eventID eventConfig, statsCollect evi
eventType eventConfig evt
evenStart eventConfig evs
eventEnd eventConfig eve
operationType eventConfig opt
dataSize eventConfig ds

Page-11
Mobius-Yellow Turtle REST APIs

Attribute Name Occurs in Short Name


execStatus execInstance exs
execResult execInstance exr
execDisable execInstance exd
execTarget execInstance, mgmtCmd ext
execMode execInstance, mgmtCmd exm
execFrequency execInstance, mgmtCmd exf
execDelay execInstance, mgmtCmd exy
execNumber execInstance, mgmtCmd exn
execReqArgs execInstance, mgmtCmd exra
execEnable mgmtCmd exe
memberType group mt
currentNrOfMembers group cnm
maxNrOfMembers group mnm
memberIDs group mid
membersAccessControlPolicyIDs group macp
memberTypeValidated group mtv
consistencyStrategy group csy
groupName group, subscription gn
locationSource locationPolicy los
locationUpdatePeriod locationPolicy lou
locationTargetId locationPolicy lot
locationServer locationPolicy lor
locationContainerID locationPolicy loi
locationContainerName locationPolicy lon
locationStatus locationPolicy lost
serviceRoles m2mServiceSubscriptionProfile svr
description mgmtCmd, mgmtObj, all management resources dc
from firmware
cmdType mgmtCmd cmt
mgmtDefinition mgmtObj, all management resources from mgd
firmware
objectIDs mgmtObj obis
objectPaths mgmtObj obps
nodeID node ni
hostedCSELink node hcl
CSEBase remoteCSE cb
M2M-Ext-ID remoteCSE mei
Trigger-Recipient-ID remoteCSE tri
requestReachability remoteCSE rr
originator request og
metaInformation request mi
requestStatus request rs
operationResult request ol
operation request opn
requestID request rid
scheduleElement schedule se
deviceIdentifier serviceSubscribedNode di
ruleLinks serviceSubscribedNode rlk
statsCollectID statsCollect sci
collectingEntityID statsCollect cei
collectedEntityID statsCollect cdi
devStatus areaNwkDeviceInfo ss
statsRuleStatus statsCollect srs
statModel statsCollect sm
collectPeriod statsCollect cp
eventNotificationCriteria subscription enc
expirationCounter subscription exc
notificationURI subscription nu
groupID subscription gpi
notificationForwardingURI subscription nfu
batchNotify subscription bn
rateLimit subscription rl

Page-12
Mobius-Yellow Turtle REST APIs

Attribute Name Occurs in Short Name


preSubscriptionNotify subscription psn
pendingNotification subscription pn
notificationStoragePriority subscription nsp
latestNotify subscription ln
notificationContentType subscription nct
notificationEventCat subscription nec
subscriberURI subscription su
version firmware, software vr
URL firmware, software url
update firmware ud
updateStatus firmware uds
install software in
uninstall software un
installStatus software ins
activate software act
deactivate software dea
activeStatus software, areaNwkInfo acts
memAvailable memory mma
memTotal memory mmt
areaNwkType areaNwkInfo ant
listOfDevices areaNwkInfo ldv
devId areaNwkDeviceInfo dvd
devType areaNwkDeviceInfo dvt
areaNwkId areaNwkDeviceInfo awi
sleepInterval areaNwkDeviceInfo sli
sleepDuration areaNwkDeviceInfo sld
listOfNeighbors areaNwkDeviceInfo lnh
batteryLevel battery btl
batteryStatus battery bts
deviceLabel deviceInfo dlb
manufacturer deviceInfo man
model deviceInfo mod
deviceType deviceInfo dty
fwVersion deviceInfo fwv
swVersion deviceInfo swv
hwVersion deviceInfo hwv
capabilityName deviceCapability can
attached deviceCapability att
capabilityActionStatus deviceCapability cas
enable deviceCapability ena
disable deviceCapability dis
currentState deviceCapability cus
reboot reboot rbo
factoryReset reboot far
logTypeId eventLog lgt
logData eventLog lgd
logActionStatus eventLog lgs
logStatus eventLog lgst
logStart eventLog lga
logStop eventLog lgo
firmwareName firmware fwnnam
softwareName software swn
cmdhPolicyName cmdhPolicy cpn
mgmtLink cmdhPolicy, activeCmdhPolicy, cmdhDefaults, cmlk
cmdhNetworkAccessRules, cmdhNwAccessRule
activeCmdhPolicyLink activeCmdhPolicy acmlk
order cmdhDefEcValue, cmdhLimits od
defEcValue cmdhDefEcValue dev
requestOrigin cmdhDefEcValue, cmdhLimits ror
requestContext cmdhDefEcValue, cmdhLimits rct
requestContextNotification cmdhDefEcValue, cmdhLimits rcn
requestCharacteristics cmdhDefEcValue, cmdhLimits rch

Page-13
Mobius-Yellow Turtle REST APIs

Attribute Name Occurs in Short Name


applicableEventCategories cmdhNetworkAccessRules aecs
applicableEventCategory cmdhEcDefParamValues, cmdhBuffer aec
defaultRequestExpTime cmdhEcDefParamValues dqet
defaultResultExpTime cmdhEcDefParamValues dset
defaultOpExecTime cmdhEcDefParamValues doet
defaultRespPersistence cmdhEcDefParamValues drp
defaultDelAggregation cmdhEcDefParamValues dda
limitsEventCategory cmdhLimits lec
limitsRequestExpTime cmdhLimits lqet
limitsResultExpTime cmdhLimits lset
limitsOpExecTime cmdhLimits loet
limitsRespPersistence cmdhLimits lrp
limitsDelAggregation cmdhLimits lda
targetNetwork cmdhNwAccessRule ttn
minReqVolume cmdhNwAccessRule mrv
backOffParameters cmdhNwAccessRule bop
otherConditions cmdhNwAccessRule ohc
maxBufferSize cmdhBuffer mbfs
storagePriority cmdhBuffer sgp
applicableCredIDs serviceSubscribedAppRule apci
allowedApp-IDs serviceSubscribedAppRule aai
allowedAEs serviceSubscribedAppRule aae

1.5.3. Primitive parameter short names


Table 1.5-3 shows short names for primitive parameters used for request and response primitives.

Table 1.5-3 Primitive parameter short names

Parameter Name XSD long name Occurs in Short Name


Operation operation Request op
To to Request, Response to
From from Request, Response fr
Request Identifier requestIdentifier Request, Response rqi
Resource Type resourceType Request ty
Content primitiveContent Request, Response pc
Role role Request rol
Originating Timestamp originatingTimestamp Request, Response ot
Request Expiration Timestamp requestExpirationTimestamp Request rqet
Result Expiration Timestamp resultExpirationTimestamp Request, Response rset
Operation Execution Time operationExecutionTime Request oet
Response Type responseType Request rt
Result Persistence resultPersistence Request rp
Result Content resultContent Request rcn
Event Category eventCategory Request, Response ec
Delivery Aggregation deliveryAggregation Request da
Group Request Identifier groupRequestIdentifier Request gid
Filter Criteria filterCriteria Request fc
Discovery Result Type discoveryResultType Request drt
Response Status Code responseStatusCode Response rsc

1.5.4. Complex data types members


Table 1.5-4 shows short names for parameters used for filter criteria and eventNotificationCriteria
primitives.

Page-14
Mobius-Yellow Turtle REST APIs

Table 1.5-4 Complex data type member short names

Member Name Occurs in Short Name


createdBefore filterCriteria, eventNotificationCriteria crb
createdAfter filterCriteria, eventNotificationCriteria cra
modifiedSince filterCriteria, eventNotificationCriteria ms
unmodifiedSince filterCriteria, eventNotificationCriteria us
stateTagSmaller filterCriteria, eventNotificationCriteria sts
stateTagBigger filterCriteria, eventNotificationCriteria stb
expireBefore filterCriteria, eventNotificationCriteria exb
expireAfter filterCriteria, eventNotificationCriteria exa
labels filterCriteria, eventNotificationCriteria lbl *
resourceType filterCriteria ty *
sizeAbove filterCriteria, eventNotificationCriteria sza
sizeBelow filterCriteria, eventNotificationCriteriay szb
contentType filterCriteria cty
limit filterCriteria lim

2. OPEN APIs
2.1. API Outline
Table 2.1-1 A summary of Mobius-YT open APIs

Interface ID Interface Name Interface Description


API-CB-R CSEBase Retrieve CSEBase retrieve with resultContent set to 1
(attributes)
API-CSR-C remoteCSE Create remoteCSE creation with resultContent set to 1
(attributes)
API-CSR-R remoteCSE Retrieve remoteCSE retrieve with resultContent set to 1
(attributes)
API-CSR-U remoteCSE Update remoteCSE update with resultContent set to 1
(attributes)
API-CSR-D RemoteCSE Delete remoteCSE delete with resultContent set to 0
(nothing)
API-AE-C AE Create AE creation with resultContent set to 1 (attributes)
API-AE-R AE Retrieve AE retrieve with resultContent set to 1 (attributes)
API-AE-U AE Update AE update with ResultContent set to 1 (attributes)
API-AE-D AE Delete AE delete with ResultContent set to 0 (nothing)
API-CNT-C Container Create Container creation with resultContent set to 2
(hierarchical address)
API-CNT-R Container Retrieve Container retrieve with resultContent set to 1
(attributes)
API-CNT-U Container Update Container update with resultContent set to 0
(nothing)
API-CNT-D Container Delete Container delete with resultContent set to 0
(nothing)
API-CIN-C ContentInstance Create contentInstance create with resultContent set to 0
(nothing)
API-CIN-R ContentInstance Retrieve Latest contentInstance retrieve
API-CIN-D CotentInstance Delete contentInstance delete with resultContent set to 0
(nothing)
API-SD-C SemanticDescriptor Create SemanticDescriptor create with resultContent set to
0 (nothing)

Page-15
Mobius-Yellow Turtle REST APIs

Interface ID Interface Name Interface Description


API-SD-R SemanticDescriptor Retrieve SemanticDescriptor retrieve with resultContent set
to 1 (attributes)
API-SD-U SemanticDescriptor Update SemanticDescriptor update with resultContent set to
0 (nothing)
API-SD-D SemanticDescriptor Delete SemanticDescriptor delete with resultContent set to
0 (nothing)
API-DIS-ResourceType Discovery with Resource Type Discovery with preferred resource type attribute
API-DIS-Label Discovery with Label Discovery with preferred Label attribute
API-DIS-Limit Discovery with Limit Discovery with preferred Limit attribute
API-DIS- Discovery with Creation time range Discovery with preferred createdBefore and
CreateBefore&CreateA createdAfter attribute
fter
API-DIS-Offset Discovery with Offset Discovery with preferred Offset attribute
API-DIS-Level Discovery with Level Discovery with preferred Level attribute
API-DIS-Multiple- Discovery with multiple filters Discovery with multiple filter criteria parameters
Filters
API-SUB-C Subscription Create Subscription create with resultContent set to 0
(nothing)
API-SUB-R Subscription Retrieve Subscription retrieve with resultContent set to 1
(attributes)
API-SUB-U Subscription Update Subscription update with resultContent set to 0
(nothing)
API-SUB-D Subscription Delete Subscription delete with resultContent set to 0
(nothing)
API-GRP-C Group Create Group create with resultContent set to 0 (nothing)
API-GRP-R Group Retrieve Group retrieve with resultContent set to 1
(attributes)
API-GRP-U Group Update Group update with resultContent set to 0 (nothing)
API-GRP-D Group Delete Group delete with resultContent set to 0 (nothing)
API-TS-C timeSeries Create timeSeries create with resultContent set to 0
(nothing)
API-TS-R timeSeries Retrieve timeSeries retrieve with resultContent set to 1
(attributes)
API-TS-U timeSeries Update timeSeries update with resultContent set to 0
(nothing)
API-TS-D timeSeries Delete timeSeries delete with resultContent set to 0
(nothing)
API-TSI-C timeSeriesInstance Create timeSeriesInstance create with resultContent set to 0
(nothing)
API-TSI-R timeSeriesInstance Retrieve timeSeriesInstance retrieve with resultContent set to
1 (attributes)
API-TSI-D timeSeriesInstance Delete timeSeriesInstance delete with resultContent set to 0
(nothing)

2.2. API Details


2.2.1 Abbreviations and Preferences
1) Abbreviations

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.

2.2.2 <CSEBase> Resource


A <CSEBase> resource represents a CSE and it is the root for all resources that are residing in the CSE.
The <CSEBase>resource doesn’t support the creation, update, and delete operations via API but only
supports retrieve operation.

1) API-CB-C

The <CSEBase>resource is not permitted to be created via API.

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

External Entity Mobius-YT

Retrieve CSEBase request

Response with CSEBase information

③ Resource URL Information


GET /mobius-yt

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET /mobius-yt HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: 12345
X-M2M-Origin:C0.2.481.1.1.232466

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 477
Content-Type: application/json
X-M2M-RI: 12345
X-M2M-RSC: 2000

{
"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

The <CSEBase> resource is not permitted to be updated via API.

4) API-CB-D

The <CSEBase> resource is not permitted to be deleted via API.

2.2.3 <remoteCSE> Resource


The <remoteCSE> resource represents a Registree CSE that is registered to the Registrar CSE and the
created <remoteCSE> locates directly under the <CSEBase> resource. Conversely each <remoteCSE>
resource also represents as a Registrar CSE. The <remoteCSE> resource will also be located directly
under the <CSEBase> resource of Registree CSE.

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>.

Table 2.2.3- 1 Universal Attributes of <remoteCSE> resource

Attribute Name Request Optionality


Create Update
@resourceName NP NP
resourceType NP NP
resourceID NP NP
parentID NP NP
accessControlPolicyIDs O O
creationTime NP NP
expirationTime O O
lastModifiedTime NP NP
labels O O
announceTo O O
announcedAttribute O O

Page-19
Mobius-Yellow Turtle REST APIs

Table 2.2.3- 2 Resource Specific Attributes of <remoteCSE> resource

Attribute Name Request Optionality Data Type Default Value and


Create Update Constraints
cseType O NP m2m:cseTypeID No default
pointOfAccess O O m2m:poaList No default
CSEBase M NP xs:anyURI No default
CSE-ID M NP m2m:ID No default
M2M-Ext-ID O O m2m:externalID No default
Trigger-Recipient-ID O O m2m:triggerRecipientID No default
requestReachability M O xs:boolean No default
nodeLink O O xs:anyURI No default

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

remoteCSE create request

Response with created remoteCSE information

③ Resource URL Information


POST /mobius-yt?rcn=1

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin CSE-ID of request originator

Page-20
Mobius-Yellow Turtle REST APIs

Content-Type application/vnd.onem2m-res+json; ty=16

⑤ Example of Request Message


POST /mobius-yt?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req12345
X-M2M-Origin: /csencube
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"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 418
Content-Location: /mobius-yt/ncube
Content-Type: application/vnd.onem2m-res+xml; ty=16
X-M2M-RI: req12345
X-M2M-RSC: 2001

{
"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:

CSE Registree Mobius-YT

remoteCSE create request

Response with created remoteCSE information

③ Resource URL Information


POST /mobius-yt?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin CSE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=16

⑤ Example of Request Message


POST /mobius-yt?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req12345
X-M2M-Origin: /csencube
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"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 0
Content-Location: /mobius-yt/ncube
Content-Type: application/vnd.onem2m-res+xml; ty=16
X-M2M-RI: req12345
X-M2M-RSC: 2001

Interface ID API-CSR-C-03
Interface Name remoteCSECreate with resultContent set to 2 (hierarchical-address)

Page-22
Mobius-Yellow Turtle REST APIs

Target Resource <remoteCSE> resource


The interface is used to send a <remoteCSE> create request attached with resultContent
set to 2 to the Mobius-YT CSEBase and receive a successful <remoteCSE> creation
response containing the hierarchical address 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:

CSE Registree Mobius-YT

remoteCSE create request

Response with created remoteCSE information

③ Resource URL Information


Interface POST /mobius-yt?rcn=2
Description
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin CSE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=16

⑤ Example of Request Message


POST /mobius-yt?rcn=2 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req12345
X-M2M-Origin: /csencube
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"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json

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:

CSE Registree Mobius-YT


Interface
Description remoteCSE create request

Response with created remoteCSE information

③ Resource URL Information


POST /mobius-yt?rcn=3

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin CSE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=16

⑤ Example of Request Message


POST /mobius-yt?rcn=3 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req12345
X-M2M-Origin: /csencube

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"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 445
Content-Location: /mobius-yt/ncube
Content-Type: application/vnd.onem2m-res+xml; ty=16
X-M2M-RI: req12345
X-M2M-RSC: 2001
{
"m2m:rce": {
"m2m:csr": {
"rn": "ncube",
"ty": 16,
"pi": "/mobius-yt",
"ri": "/mobius-yt/ncube2",
"ct": "20161219T081610",
"et": "20171219T081610",
"lt": "20161219T081610",
"st": 0,
"cb": "//myoperator.com/ncube",
"csi": "0.2.481.1.0001.001.000111",
"rr": true,
"cst": 1
},
"m2m:uri": "/mobius-yt/ncube"
}
}
2) API-CSR-R

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

External Entity Mobius-YT

remoteCSE retrieve request

Response with requested remoteCSE information

③ Resource URL Information


GET /mobius-yt/ncube?rcn=1

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin Entity ID of the request originator

⑤ Example of Request Message


GET /mobius-yt/ncube?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req12346
X-M2M-Origin: /csencube

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 418
Content-Type: application/json
X-M2M-RI: req12346
X-M2M-RSC: 2000

{
"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.

External Entity Mobius-YT

remoteCSE update request

Response with updated remoteCSE information

③ Resource URL Information


PUT /mobius-yt/ncube?rcn=1

④ Http Header Information


Header Value
Accept application/json
X-M2M-RI Request ID of external entity
X-M2M-Origin Entity ID of the request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


This example is to demonstrate the update of the <pointOfAccess> attribute of
<remoteCSE> resource.
PUT /mobius-yt/ncube?rcn=1 HTTP/1.1
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"
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 431
Content-Type: application/vnd.onem2m-res+json
X-M2M-RI: req21345
X-M2M-RSC: 2004
{
"m2m:csr": {
"pi": "/mobius-yt",
"ty": 16,
"ct": "20161219T071000",

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.

External Entity Mobius-YT

Interface remoteCSE update request


Description Response with updated remoteCSE information

③ Resource URL Information


PUT /mobius-yt/ncube?rcn=0

④ Http Header Information


Header Value
Accept application/json
X-M2M-RI Request ID of external entity
X-M2M-Origin Entity ID of the request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


This example is to demonstrate the update of the <pointOfAccess> attribute of
<remoteCSE> resource.
PUT /mobius-yt/ncube?rcn=0 HTTP/1.1

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"
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
Content-Type: application/vnd.onem2m-res+json
X-M2M-RI: req21345
X-M2M-RSC: 2004
4) API-CSR-D

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.

External Entity Mobius-YT


Interface
Description
remoteCSE delete request

Response with only response status code

③ Resource URL Information


DELETE /mobius-yt/ncube?rcn=0

④ Http Header Information


Header Value
Accept application/json
X-M2M-RI Request ID of external entity
X-M2M-Origin Entity ID of the request originator
⑤ Example of Request Message
This example is to demonstrate the delete of the <remoteCSE> resource.

Page-29
Mobius-Yellow Turtle REST APIs

DELETE /mobius-yt/ncube?rcn=0 HTTP/1.1


Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req12345
X-M2M-Origin: /csencube

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: req12345
X-M2M-RSC: 2002

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.

External Entity Mobius-YT

Interface remoteCSE delete request


Description Response with deleted remoteCSE information

③ Resource URL Information


DELETE /mobius-yt/ncube?rcn=1

④ Http Header Information


Header Value
Accept application/json
X-M2M-RI Request ID of external entity
X-M2M-Origin Entity ID of the request originator
⑤ Example of Request Message
This example is to demonstrate the delete of the <remoteCSE> resource.
DELETE /mobius-yt/ncube?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req12345
X-M2M-Origin: /csencube

Page-30
Mobius-Yellow Turtle REST APIs

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 147
Content-Type: application/json
X-M2M-RI: req12345
X-M2M-RSC: 2002
{
"m2m:csr": {
"pi": "/mobius-yt",
"ty": 16,
"ct": "20161219T081610",
"ri": "/mobius-yt/ncube",
"rn": "ncube",
"lt": "20161219T081610",
"et": "20171219T081610"
}
}

2.2.4 <AE> Resource


The <AE> resource represents information about an Application Entity that is registered to a CSE. The
originator of a <AE> create request is and only can be an AE. A CSE is not allowed to initiate a <AE>
create request.

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

Table 2.2.4. 1 Universal Attributes of <AE> resource

Attribute Name Request Optionality


Create Update
@resourceName O NP
resourceType NP NP
resourceID NP NP
parentID NP NP
accessControlPolicyIDs O O
creationTime NP NP
expirationTime O O
lastModifiedTime NP NP
labels O O
announceTo O O
announcedAttribute O O
Table 2.2.4. 2 Resource Specific Attributes of <AE> resource

Attribute Name Request Optionality Data Type Default Value and


Create Update Constraints
appName O O xs:string No default
App-ID M NP xs:string No default
AE-ID NP NP m2m:ID No default
pointOfAccess O O m2m:poaList No default
ontologyRef O O xs:anyURI No default
nodeLink NP NP xs:anyURI No default
requestReachability M O xs:boolean No default
contentSerialization O O m2m:serializations No default
1) API-AE-C

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 Registree Mobius-YT Registrar

AE create request

Response with the created AE information

Page-32
Mobius-Yellow Turtle REST APIs

③ Resource URL Information


POST /mobius-yt?rcn=1
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=2

⑤ Example of Request Message


POST /mobius-yt?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req34521
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=2

{
"m2m:ae":
{
"rn": "temp_sensor",
"api": "A01.com.company.tempApp1",
"rr": true
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 213
Content-Location: /mobius-yt/temp_sensor
Content-Type: application/json
X-M2M-RI: req34521
X-M2M-RSC: 2001

{
"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

A temperature sensor is registered to Mobius-YT platform by sending a <AE>


registration request to the Mobius-YT CSEBase.
① Resource Structure
Mobius-yt

temp_sensor
② Call Flow between the request originator and the hosting CSE is shown as
below:

AE Registree Mobius-YT Registrar

AE create request

Response with the created AE information

③ Resource URL Information


POST /mobius-yt?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=2

⑤ Example of Request Message


POST /mobius-yt?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req34522
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=2

{
"m2m:ae":
{
"rn": "temp_sensor",
"api": "A01.com.company.tempApp1",
"rr": true
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 213
Content-Location: /mobius-yt/temp_sensor
Content-Type: application/json
X-M2M-RI: req34522
X-M2M-RSC: 2001
2) API-AE-R

Interface ID API-AE-R

Page-34
Mobius-Yellow Turtle REST APIs

Interface Name AE retrieve with resultContent set to 1 (attributes)


Target Resource Requested <AE> resource
The interface is used to send a retrieve request attached with resultContent set to 1 to the
<AE> resource that has been created before and receive a response containing attributes
of the requested <AE> resource.

① 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.

External entity Mobius-YT

AE retrieve request

Response with the requested AE information

③ Resource URL Information


GET /mobius-yt/temp_sensor?rcn=1
④ Http Header Information
Interface Header Value
Description
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET /mobius-yt/temp_sensor?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req45321
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 226
X-M2M-RI: req45321
X-M2M-RSC: 2000

{
"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

External Entity Mobius-YT

AE update request

Response with the updated AE information

Interface ③ Resource URL Information


Description PUT /mobius-yt/temp_sensor?rcn=1
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


PUT /mobius-yt/temp_sensor?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req63435
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

{
"m2m:ae":
{
"poa": ["http://192.168.0.10:9090"]
}
}

⑥ Example of Response Message

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

External Entity Mobius-YT


Interface
Description
AE update request

Response with the updated AE information

③ Resource URL Information


PUT /mobius-yt/temp_sensor?rcn=0
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

Page-37
Mobius-Yellow Turtle REST APIs

Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


PUT /mobius-yt/temp_sensor?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req63435
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

{
"m2m:ae":
{
"poa": ["http://192.168.0.10:9090"]
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 247
Content-Type: application/vnd.onem2m-res+json
X-M2M-RI: req63435
X-M2M-RSC: 2004
4) API-AE-D

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

External Entity Mobius-YT

AE delete request

Response with no response body

Interface ③ Resource URL Information


Description DELETE /mobius-yt/temp_sensor?rcn=0
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


DELETE /mobius-yt/temp_sensor?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req63456
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
Content-type: application/json
X-M2M-RI: req63456
X-M2M-RSC: 2002

2.2.5 <Container> Resource


The <container> resource represents a container for data instances. It is used to share information with
other entities and potentially to track the data. A <container> resource has no associated content. It has only
attributes and child resources.

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.

Table 2.2.5. 1 Universal Attributes of <container> resource

Attribute Name Request Optionality


Create Update
@resourceName O NP
resourceType NP NP
resourceID NP NP
parentID NP NP
accessControlPolicyIDs O O
creationTime NP NP
expirationTime O O
lastModifiedTime NP NP
stateTag NP NP
labels O O
announceTo O O
announcedAttribute O O
Table 2.2.5. 2: Resource Specific Attributes of <container> resource

Attribute Name Request Optionality Data Type Default Value and


Create Update Constraints
creator O NP m2m:ID No default
maxNrOfInstances O O xs:nonNegativeInteger No default
maxByteSize O O xs:nonNegativeInteger No default
maxInstanceAge O O xs:nonNegativeInteger No default
currentNrOfInstances xs:nonNegativeInteger No default
NP NP (This is generated by the
hosting CSE and limited by
the maxNrOfInstances)
currentByteSize xs:nonNegativeInteger No default
NP NP (This is generated by the
hosting CSE and limited by
the maxByteSize)
locationID O O xs:anyURI No default
ontologyRef O O xs:anyURI No default
1) API-CNT-C

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

External Entity Mobius-YT

Container create request

Response with the created container information

③ Resource URL Information


POST /mobius-yt/temp_sensor?rcn=2
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=3

⑤ Example of Request Message


POST /mobius-yt/temp_sensor?rcn=2 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req98367
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=3

{
"m2m:cnt":
{
"rn": "temp_container"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 47
Content-Location: /mobius-yt/temp_sensor/temp_container
Content-Type: application/vnd.onem2m-res+json;ty=3
X-M2M-RI: req98367
X-M2M-RSC: 2001

{
"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

Target Resource <container> resource


The interface is used to send a <container> create request attached with resultContent
set to 3 under the <AE> resource and receive a successful <container> creation response
including both the hierarchical address and attributes representation of the created
<container> resource.

① Resource Structure

Mobius-yt

temp_sensor

temp_container

② Call Flow

External Entity Mobius-YT

Container create request

Response with the created container information

③ Resource URL Information


POST /mobius-yt/temp_sensor?rcn=3
Interface ④ Http Header Information
Description
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=3

⑤ Example of Request Message


POST /mobius-yt/temp_sensor?rcn=3 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req98368
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=3

{
"m2m:cnt":
{
"rn": "temp_container"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 288
Content-Location: /mobius-yt/temp_ae/temp_container
Content-Type: application/vnd.onem2m-res+json;ty=3
X-M2M-RI: req98368
X-M2M-RSC: 2001

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

External Entity Mobius-YT


Interface
Description Container retrieve request

Response with the requested container information

③ Resource URL Information


GET /mobius-yt/temp_ae/temp_container?rcn=1
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET /mobius-yt/temp_ae/temp_container?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579

Page-43
Mobius-Yellow Turtle REST APIs

Accept: application/json
X-M2M-RI: req67392
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 224
Content-Type: application/json
X-M2M-RI: req67392
X-M2M-RSC: 2000

{
"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

External Entity Mobius-YT

Container update request

Response with no response body representation

③ Resource URL Information


PUT /mobius-yt/temp_sensor/temp_container?rcn=0

Interface ④ Http Header Information


Description
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of 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: req33451
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

{
"m2m:cnt":
{
"mni": 10000,
"lbl": ["temperature repo"]
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: req33451
X-M2M-RSC: 2004

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

External Entity Mobius-YT

Container delete request

Response with no response body


Interface
Description

③ Resource URL Information


DELETE /mobius-yt/temp_sensor/temp_container?rcn=0
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


DELETE /mobius-yt/temp_sensor/temp_container?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req10098
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
X-M2M-RI: req10098
X-M2M-RSC: 2002

2.2.6 <ContentInstance> Resource


The <contentInstance> resource represents a data instance stored in the <container> resource.

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.

Table 2.2.6. 1 Universal Attributes of <contentInstance> resource

Attribute Name Request


Optionality
Create
@resourceName O
resourceType NP
resourceID NP
parentID NP
expirationTime O
creationTime NP
lastModifiedTime NP
stateTag NP
labels O
announceTo O
announcedAttribute O

Table 2.2.6. 2 Resource Specific Attributes of <contentInstance> resource

Attribute Name Request Optionality Data Type Default Value and


Create Constraints
creator O m2m:ID
contentInfo O m2m:contentInfo No default
contentSize NP xs:nonNegativeInteger No default
ontologyRef O xs:anyURI No default
content M xs:anySimpleType No default (Transfer
encoding may be applied,
and indicated applied
encoding as part of the
contentInfo attribute)
1) API-CIN-C

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

External Entity Mobius-YT

ContentInstance create request

Response with no http response body

③ Resource URL Information


POST /mobius-yt/temp_sensor/temp_container?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=4

⑤ Example of 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: req11629
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=4

{
"m2m:cin":
{
"con": "20"
}
}

⑥ Example of Response Message

Page-48
Mobius-Yellow Turtle REST APIs

HTTP/1.1 201 Created


Accept: application/json
Content-Length: 0
Content-Location: /mobius-
yt/temp_sensor/temp_container/temperature-20170101125630
X-M2M-RI: req11629
X-M2M-RSC: 2001
2) API-CIN-R

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

Interface External Entity Mobius-YT


Description
Latest ContentInstance retrieve request

Response with the latest contentInstance information

③ Resource URL Information


GET /mobius-yt/temp_sensor/temp_container/latest
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET /mobius-yt/temp_sensor/temp_container/latest HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req113245
X-M2M-Origin: Cae201623213

Page-49
Mobius-Yellow Turtle REST APIs

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 271
Content-Type: application/json
X-M2M-RI: req113245
X-M2M-RSC: 2000

{
"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

External Entity Mobius-YT

Latest contentInstance delete request

Response with no response body

③ Resource URL Information


DELETE /mobius-yt/temp_sensor/temp_container/latest
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


DELETE /mobius-yt/temp_sensor/temp_container/latest HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req666125
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
X-M2M-RI: req666125
X-M2M-RSC: 2002
2.2.7 <SemanticDecriptor> Resource
The <semanticDescriptor> resource is used to store a semantic description pertaining to a resource and
potentially sub-resources. Such a description may be provided according to ontologies. The semantic
information is used by the semantic functionalities of the oneM2M system and is also available to
applications or CSEs.

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

Table 2.2.7. 1 Universal Attributes of <semanticDescriptor> resource

Attribute Name Request Optionality


Create Update
@resourceName O NP
resourceType NP NP
resourceID NP NP
parentID NP NP
expirationTime O O
accessControlPolicyIDs O O
creationTime NP NP
lastModifiedTime NP NP
labels O O
Table 2.2.7. 2 Resource Specific Attributes of <semanticDescriptor> resource

Attribute Name Request Optionality Data Type Default Value and


Create Update Constraints
creator O NP m2m:ID No default
descriptorRepresenation M O m2m:descriptorRepresentation application/rdf+xml:1
semanticOpExec NP O m2m:sparql No default
descriptor M O xs:base64Binary No default
ontologyRef O O xs:anyURI No default
relatedSemantics O O List of xs:anyURI No default
1) API-SD-C

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

External Entity Mobius-YT

semanticDesriptor create request

Response with no http response body

Page-52
Mobius-Yellow Turtle REST APIs

③ Resource URL Information


POST /mobius-yt/temp_sensor/temp_container?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=24

⑤ Example of 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: req111265
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=24

{
"m2m:sd":
{
"rn":"semantic_describer",
"dspt": "application/rdf+json:1",
"dsr":
"PHJkZjpSREYNCPHJkZjpSREYNCPHJkZjpSREYNCPHJkZjpSREYNC4="
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Accept: application/json
Content-Length: 0
Content-Location: /mobius-
yt/temp_sensor/temp_container/semantic_describer
Content-Type: application/vnd.onem2m-res+json;ty=24
X-M2M-RI: req111265
X-M2M-RSC: 2001
2) API-SD-R

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

External Entity Mobius-YT

semanticDesriptor retrieve request


Response with attributes representation of
the requested <semanticDecriptor> resource

③ Resource URL Information


GET /mobius-
yt/temp_sensor/temp_container/semantic_describer?rcn=1
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET / mobius-
yt/temp_sensor/temp_container/semantic_describer?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req122245
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 263
X-M2M-RI: req122245
X-M2M-RSC: 2000

{
"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

External Entity Mobius-YT

Interface
Description semanticDesriptor update request

Response with no response body

③ Resource URL Information


PUT /mobius-
yt/temp_sensor/temp_container/semantic_describer?rcn=0
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


PUT /mobius-
yt/temp_sensor/temp_container/semantic_describer?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: re12290
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

Page-55
Mobius-Yellow Turtle REST APIs

{
"m2m:sd":
{
"or": "ontology.ref.com/semantics"
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: re12290
X-M2M-RSC: 2004

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

External Entity Mobius-YT

semanticDesriptor delete request

Response with no response body

③ Resource URL Information


DELETE /mobius-
yt/temp_sensor/temp_container/semantic_describer?rcn=0
④ Http Header Information

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

⑤ Example of Request Message


DELETE /mobius-
yt/temp_sensor/temp_container/semantic_describer?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req998312
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
X-M2M-RI: req998312
X-M2M-RSC: 2002

2.2.8 Resource Discovery and Conditional Retrieval


The Discovery CSF (DIS) searches information about applications and services as contained in
attributes and resources.

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.

Table 2.2.8-1 Interpretation of filterUsage

Value Interpretation Note


1 Discovery Criteria
2 Conditional Retrieval This is the default value when the filterUsage
condition is not present in a Retrieve request.
3 IPE On-demand Discovery

Table 2.2.8-2 Type definition of m2m:filterCriteria

Element Path Element Data Type Multiplicity


createdBefore m2m:timestamp 0..1
createdAfter m2m:timestamp 0..1
labels m2m:labels 0..1
resourceType list of m2m:resourceType 0..1
contentType m2m:typeOfContent 0..n
attribute m2m:attribute 0..n
filterUsage m2m:filterUsage 0..1
limit xs:nonNegativeInteger 0..1
level xs:positiveInteger 0..1
offset xs:positiveInteger 0..1

A group of resources shown as below are created with different label values for demonstration of
discovery operations.

Table 2.2.8-3 Resource representations

ResourceType Resource attributes representation in JSON


AE {
"temp_sensor" "m2m:ae": {
"pi": "/mobius-yt",
"ty": 2,
"ct": "20170103T092533",
"ri": "/mobius-yt/temp_sensor",
"rn": "temp_sensor",
"lbl": [
"temp_sensor",
"sensor",
"indoor"
],
"lt": "20170104T030832",
"et": "20180103T092533",
"api": "A01.com.company.temptApp1",
"aei": "Cae201623213",
"rr": true
}
}
AE {
"temp_sensor02" "m2m:ae": {
"pi": "/mobius-yt",
"ty": 2,
"ct": "20170104T030802",

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

"temp_controller" "pi": "/mobius-yt/temp_sensor",


"ty": 3,
"ct": "20170104T060527",
"ri": "/mobius-yt/temp_sensor/temp_controller",
"rn": "temp_controller",
"lbl": [
"sensor control",
"controller"
],
"lt": "20170104T060527",
"et": "20180104T060527",
"st": 0,
"mni": 1000,
"cni": 0,
"cbs": 0
}
}

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

External Entity Mobius-YT

Discovery request with resource type filter criteria

Response with hierarchical address of matched resources if any

Interface ② Resource URL Information


Description GET /mobius-yt?fu=1&ty=RESOURCE-TYPE-VALUE
③ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

④ Example of Request Message


GET /mobius-yt?fu=1&ty=2 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req55312
X-M2M-Origin: Cae201623213

⑤ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 87

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

External Entity Mobius-YT

Discovery request with label filter criteria

Response with hierarchical address of matched resources if any

② Resource URL Information


GET /mobius-yt?fu=1&lbl=LABEL-VALUE
③ Http Header Information
Header Value
Accept application/ xml
Interface X-M2M-RI Request ID of external entity
Description X-M2M-Origin AE-ID of request originator

④ 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

GET /mobius-yt?fu=1&lbl=indoor HTTP/1.1


Host: yt.iotmobius.com:7579
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/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

External Entity Mobius-YT

Discovery request with limit filter criteria

Response with hierarchical address of matched resources if any

② Resource URL Information


GET /mobius-yt?fu=1&lim=LIMIT-VALUE
Interface
Description
③ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

④ 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

External Entity Mobius-YT

Discovery request with


createBefore and createdAfter filter criteria

Response with hierarchical address of matched resources if any

② Resource URL Information


GET /mobius-yt?fu=1&crb=CREATED-BEFORE&cra=CREATED-AFTER

Interface ③ Http Header Information


Description Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

④ 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

External Entity Mobius-YT

Discovery request with


offset filter criteria

Response with hierarchical address of matched resources if any

② Resource URL Information


GET /mobius-yt?fu=1&ofst=OFFSET-VALUE
Interface
Description ③ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

④ 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

External Entity Mobius-YT

Discovery request with


level filter criteria

Response with hierarchical address of matched resources if any

② Resource URL Information


Interface GET /mobius-yt?fu=1&lvl=LEVEL-VALUE
Description ③ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

④ 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

External Entity Mobius-YT

Discovery request with


multiple filter criteria parameters

Response with hierarchical address of matched resources if any

② Resource URL Information


GET /mobius-yt?fu=1&lbl=LABEL-
VALUE&lvl=3&ofst=1&lim=10&crb=TIME-EXPIRATION-AFTER

③ Http Header Information


Interface Header Value
Description
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

④ 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"
}

2.2.9 <Subscription> Resource


2.2.9.1 Introduction
The <subscription> resource contains subscription information for its subscribed-to resource. The
subscription resource is represented as a resource subscription in the CSE resource structure as a direct
child of the subscribed-to resource.

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

- The Subscription resource subscriber ID i.e. AE-ID or CSE-ID.


- The hosting CSE-ID where the subscribed-to resource is existed.
- The address of subscribed-to resource i.e. the URI of subscribed-to resource.
- Notification URL to which notifications will be sent whenever modifications to the subscribed-
to resource are tracked.

2.2.9.2 Notification Working Principle


oneM2M specification defines an attribute notificationEventType to indicate the event type that trigger

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:

- Update to attributes of the subscribed-to resource,


- Creation of a direct child resource of the subscribed-to resource,
- Deletion of a direct child resource of the subscribed-to resource, and

Notification Procedures for modified resources case are specified 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

- oneM2M compliant Resource-ID: The resource-ID can be represented in structured/unstructured


CSE-relative-resource-ID, structured/unstructured SP-Relative-Resource-ID, or
structured/unstructured Absolute-Resource-ID. e.g. Structured SP-relative-AE-ID:
http://<IP>:<port>/CSE-ID/CSE-Name/AE-ID
- Identifier compliant with a oneM2M supported protocol binding such as HTTP and MQTT.
For example, MQTT defines URI format to be used in the attribute pointOfAccess as
mqtt://<authority> or mqtts://<authority> (when TLS is applied). Note that oneM2M MQTT
binding protocol specification still has no definition on the structure of the notification URL.
Mobius-YT implements the notification URL in MQTT in this way mqtt://<MQTT-broker-
IP>:<port>/<AE-ID-of-TAGET-DEVICE> e.g. the notificationURL attribute with field value
look like "nu":["mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729784"]
where the MQTT port is omitted because MQTT default port (1883) is implicitly used. In
case if non-default MQTT port (1883) is used, the port has to be explicitly specified.

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.

Notification pattern in protocol level is defined as following:

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.

Table 2.2.9-1 Universal Attributes of <subscription> resource

Attribute Name Request Optionality


Create Update
@resourceName O NP
resourceType NP NP
resourceID NP NP
parentID NP NP
accessControlPolicyIDs O O
creationTime NP NP
expirationTime O O
lastModifiedTime NP NP
labels O O

Page-71
Mobius-Yellow Turtle REST APIs

Table 2.2.9-2 Resource Specific Attributes of <subscription> resource

Attribute Name Request Data Type Default Value and


Optionality Constraints
Create Update
eventNotificationCriteria m2m:eventNotificationCri Default behaviour is
O O teria notification on
Update_of_Resource
expirationCounter O O xs:positiveInteger No default
notificationURI M O list of xs:anyURI No default
groupID O O xs:anyURI No default
notificationForwardingURI O O xs:anyURI No default
batchNotify O O m2m:batchNotify No default
rateLimit O O m2m:rateLimit No default
preSubscriptionNotify O NP xs:positiveInteger No default
pendingNotification O O m2m:pendingNotification No default
notificationStoragePriority O O xs:positiveInteger No default
latestNotify O O xs:boolean No default
notificationContentType m2m:notificationContent No default
O O
Type
notificationEventCat O O m2m:eventCat No default
creator O NP m2m:ID No default
subscriberURI O NP xs:anyURI No default

Table 2.2.9-3 Interpretation of notificationEventType

Value Interpretation Note


1 Update_of_Resource Default value
3 Create_of_Direct_Child_Resource
4 Delete_of_Direct_Child_Resource
Table 2.2.9-4 Interpretation of notificationContentType

Value Interpretation Note


1 All Attributes Default value
2 Modified Attributes
3 ResourceID
Table 2.2.9-5 Interpretation of pendingNotification

Value Interpretation Note


1 sendLatest
2 sendAllPending

2.2.9.3 Subscription CRUD API


1) API-SUB-C

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

Subscription create request

Response with no http response body included

③ Resource URL Information


POST /mobius-yt/temp_sensor/temp_container?rcn=0

④ Http Header Information


Header Value

Accept application/ json


X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=23

⑤ 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.

Request message example:


POST /mobius-yt/temp_sensor/temp_container?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req14335
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=23

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
}
}

Example of Response Message


HTTP/1.1 201 Created
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
2) API-SUB-R

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

Subscription retrieve request

Response with Attributes representation of


the requested <subscription> resource

③ Resource URL Information


GET /mobius-yt/temp_sensor/temp_container/sub_monitor?rcn=1
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET /mobius-yt/temp_sensor/temp_container/sub_monitor?rcn=1
HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req11115
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 318
X-M2M-RI: req11115
X-M2M-RSC: 2000

{
"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

Response with no http response body included

③ Resource URL Information


PUT /mobius-
yt/temp_sensor/temp_container/sub_monitor?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example: In this example, we try to update attributes of the <subscription>


resource sub_monitor including attribute pendingNotification is update with
new field value of 2 indicating all pending notifications will be send to the
subscriber.

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
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: req109239
X-M2M-RSC: 2004

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

Subscription delete request

Response with no http response body included

③ Resource URL Information


DELETE /mobius-yt/temp_sensor/temp_container/sub_monitor?rcn=0
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


DELETE /mobius-yt/temp_sensor/temp_container/sub_monitor?rcn=0
HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req9992125
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
X-M2M-RI: req9992125
X-M2M-RSC: 2002
2.2.9.4 Use cases: Application of subscription and notification mechanism
In this section, we introduce two use cases that apply subscription and notification mechanism, resource
monitoring and devices control use case. oneM2M AE resource primitive allows to create two direct
children <container> resources to store the status information and control information, named
temp_container and temp_controller, respectively, as depicted in figure 2.2.9.4-1. The device and
application which both are modelled as AE can implement the controlling and monitoring purpose
through creation of <subscription> resource under corresponding <container> resource temp_controller
and temp_container, respectively.

Page-78
Mobius-Yellow Turtle REST APIs

Mobius-yt

temp_sensor

temp_container

sub_monitor
temperature-20170101125630

temperature-20170101125630

temp_controller

sub_control

Figure 2.2.9.4-1 Resource structure of Mobius-YT for controlling and monitoring

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.

Use Case I: Subscription and notification for smart application monitoring

Secenario I: Notification-for-update-of-subscribed-to-resource

Scenario Name Notification-for-update-of-subscribed-to-resource


Description ① Resource Structure

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

We assume there is three entities, an AE (an IoT application-A) that initiates a


<subscription> resource sub_monitor create request to the target <container>
temp_container, an AE (IoT application-B) that has access right to update the <container>
resource temp_container, the hosting CSE.
Call flows among these three entities are as following:
- The AE (IoT-application-A) sends a a <subscription> resource sub_monitor create
request to the target <container> temp_container;
- The AE (IoT-application-B) sends a subscribed-to-resource (<container>) update
request;
- The hosting CSE sends a notification to the subscriber and the subscriber sends
back an acknowledgement.

a. IoT-Application-A subscribe to <container> resource

① Call flow
AE (IoT-
Mobius-YT
application-A)

Procedures Authenticated
User
Subscription create request

Response with attribute representation


of the created <subscription> resource

② Resource URL Information


POST /mobius-yt/temp_sensor/temp_container?rcn=0

Page-80
Mobius-Yellow Turtle REST APIs

③ Http Header Information


Header Value

Accept application/ json


X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=23

④ 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.

Request message example:


POST /mobius-yt/temp_sensor/temp_container?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req14335
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=23

{
"m2m:sub":
{
"rn": "sub_monitor01",
"enc": {
"net": [1]
},

"nu":["mqtt://iot.ocean.org/mbroker/S0.2.481.1.20160326004729
784"],
"nct": 2,
"pn": 1
}
}

Example of Response Message


HTTP/1.1 201 Created
Content-Length: 0
Content-Location: /mobius-
yt/temp_sensor/temp_container/sub_monitor01
Content-Type: application/json
X-M2M-RI: req14335
X-M2M-RSC: 2001

{
"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
}
}

b. IoT-Application-B updates the subscribed-to-<container>

① Call flow
AE (IoT-
Mobius-YT
application-B)

Authenticated Subscribed-to-<container> update request


User

Response with no http response body included

② Resource URL Information


PUT /mobius-yt/temp_sensor/temp_container?rcn=0

③ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

④ Example: The update attributes of the <container> resource temp_container


including attribute maxNumberofInstance is update with new field value of
200000 as well as new labels field value.

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

c. Hosting CSE sends notification to subscriber

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.

We assume the entity (mobius-yt) has subscribed to Topic /oneM2M/resp/mobius-


yt/+ in order to receive notification acknowledgement while the entity has subscribed to
Topic /oneM2M/req/+/S0.2.481.1.20160326004729784 in order to receive
notification request from any entity.

① Call flow

IoT-application-A (subscriber) Hosting CSE

Notification to the
resource subscriber
Authenticated
User
ACK

② Resource URL information


The hosting CSE PUBLISH notification request associated with Topic
/oneM2M/req/mobius-yt/S0.2.481.1.20160326004729784/json
③ HTTP Header information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
④ Example
Request message
The hosting CSE PUBLISH the notification request message in the payload associated with
Topic /oneM2M/req/mobius-yt/S0.2.481.1.20160326004729784/json
{
"m2m:sgn":
{
"nev":
{
"rep":
{
"m2m:cnt":
{
"mni": 200000,
"lbl": ["resource-monitoring"],
"lt": "20170104T072540",
"st": 5
}
}
},

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

Scenario Name Notification-for-child-create-of-subscribed-to-resource


① Resource Structure

Mobius-yt

temp_sensor

temp_container

sub_monitor02
temperature-20170101125630

temperature-20170101125630

temp_controller

sub_control

Description ② Call Flow


IoT application
Hosting CSE AE
(subscriber)
Subscribe to
the container resource
Authenticated Child resource
User
Resource created response creation request to
the subscribed-to-resource
Resource created response
Notification to subscriber
ACK

We assume there is three entities, an AE (an IoT application-A) that initiates a


<subscription> resource sub_monitor create request to the target <container>
temp_container, an AE (IoT application-B) that has access right to create any child
resource under the <container> resource temp_container, the hosting CSE.
Call flows among these three entities are as following:
- The AE (IoT-application-A) sends a a <subscription> resource sub_monitor create
request to the target <container> temp_container;
- The AE (IoT-application-B) sends a <contentInstance> create request to the
subscribed-to-resource (<container>);

Page-84
Mobius-Yellow Turtle REST APIs

- The hosting CSE sends a notification to the subscriber and the subscriber sends
back an acknowledgement.

a. IoT-Application-A subscribe to <container> resource

① Call flow
AE (IoT-
Mobius-YT
application-A)

Authenticated Subscription create request


User

Response with attribute representation


of the created <subscription> resource

② Resource URL Information


POST /mobius-yt/temp_sensor/temp_container?rcn=0

③ Http Header Information


Header Value

Accept application/ json


X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=23

④ 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.

Request message example:


POST /mobius-yt/temp_sensor/temp_container?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req14335
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=23

{
"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
}
}

Example of Response Message


HTTP/1.1 201 Created
Content-Length: 0
Content-Location: /mobius-
yt/temp_sensor/temp_container/sub_monitor02
Content-Type: application/json
X-M2M-RI: req14335
X-M2M-RSC: 2001

{
"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
}
}

b. Creation of child resource of the subscribed-to-<container>

① Call flow
AE (IoT-
Mobius-YT
application-B)

Authenticated Child resource creation of


User the subscribed-to-<container>

Response with no http response body included

② Resource URL Information


POST /mobius-yt/temp_sensor/temp_container?rcn=0

③ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json?ty=4

④ Example: Create a new contentInstance under the <container> resource


temp_container.

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

c. Hosting CSE sends notification to subscriber

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.

We assume the entity (mobius-yt) has subscribed to Topic /oneM2M/resp/mobius-


yt/+ in order to receive notification acknowledgement while the entity has subscribed to
Topic /oneM2M/req/+/S0.2.481.1.20160326004729795 in order to receive
notification request from any entity.

① Call flow

IoT-application-A (subscriber) Hosting CSE

Notification to the
resource subscriber
Authenticated
User
ACK

② Resource URL information


The hosting CSE PUBLISH notification request associated with Topic
/oneM2M/req/mobius-yt/S0.2.481.1.20160326004729795/json
③ HTTP Header information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
④ Example
Request message

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"
}
}

Secenario III: Notification-for-child-delete-of-subscribed-to-resource

Scenario Name Notification-for-child-delete-of-subscribed-to-resource


① Resource Structure

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

We assume there is three entities, an AE (an IoT application-A) that initiates a


<subscription> resource sub_monitor create request to the target <container>
temp_container, an AE (IoT application-B) that has access right to delete any child
resource under the <container> resource temp_container, the hosting CSE.
Call flows among these three entities are as following:
- The AE (IoT-application-A) sends a a <subscription> resource sub_monitor create
request to the target <container> temp_container;
- The AE (IoT-application-B) sends a <contentInstance> delete request to the
subscribed-to-resource (<container>);
- The hosting CSE sends a notification to the subscriber and the subscriber sends
back an acknowledgement.

a. IoT-Application-A subscribe to <container> resource

① Call flow
AE (IoT-
Mobius-YT
application-B)

Authenticated Subscription create request


User

Response with attribute representation


of the created <subscription> resource

② Resource URL Information


POST /mobius-yt/temp_sensor/temp_container?rcn=0

③ Http Header Information


Procedures Header Value

Accept application/ json


X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=23

④ 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

pendingNotification is set to value 1 indicating only sending latest pending notifications to


the subscriber.

Request message example:


POST /mobius-yt/temp_sensor/temp_container?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req14335
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=23

{
"m2m:sub":
{
"rn": "sub_monitor03",
"enc": {
"net": [4]
},

"nu":["mqtt://iot.ocean.org/mbroker/S0.2.481.1.201603260047299
82"],
"nct": 2,
"pn": 1
}
}

Example of Response Message


HTTP/1.1 201 Created
Content-Length: 0
Content-Location: /mobius-
yt/temp_sensor/temp_container/sub_monitor03
Content-Type: application/json
X-M2M-RI: req14335
X-M2M-RSC: 2001

{
"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
}
}

b. Creation of child resource of the subscribed-to-<container>

① Call flow

Page-90
Mobius-Yellow Turtle REST APIs

AE (IoT-
Mobius-YT
application-B)

Authenticated Child resource delete of


User the subscribed-to-<container>

Response with no http response body included

② Resource URL Information


Delete an oldest <contentInstance> resource from the <container>
temp_container:
DELETE /mobius-yt/temp_sensor/temp_container/oldest?rcn=0

③ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

④ Example: Delete an oldest <contentInstance> resource from the <container>


temp_container:

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)

c. Hosting CSE sends notification to subscriber

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.

We assume the entity (mobius-yt) has subscribed to Topic /oneM2M/resp/mobius-


yt/+ in order to receive notification acknowledgement while the entity has subscribed to
Topic /oneM2M/req/+/S0.2.481.1.20160326004729982 in order to receive
notification request from any entity.

① Call flow

Page-91
Mobius-Yellow Turtle REST APIs

IoT-application-A (subscriber) Hosting CSE

Notification to the
resource subscriber
Authenticated
User
ACK

② Resource URL information


The hosting CSE PUBLISH notification request associated with Topic
/oneM2M/req/mobius-yt/S0.2.481.1.20160326004729982/json
③ HTTP Header information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
④ Example
Request message
The hosting CSE PUBLISH the notification request message in the payload associated with Topic
/oneM2M/req/mobius-yt/S0.2.481.1.20160326004729982/json
{
"m2m:sgn":
{
"nev":
{
"rep":
{
{
"m2m:cin":
{
"pi": "/mobius-yt/temp_sensor/temp_container",
"ty": 4,
"ct": "20170106T072352",
"ri": "/mobius-yt/temp_sensor/temp_container/4-
20170106072352694gA9G",
"rn": "4-20170106072352694gA9G",
"lt": "20170106T072352",
"et": "20180106T072352",
"st": 1,
"mni": 10000,
"cs": 2
}
}
}
},
"sur":"S0.2.481.1.20160326004729982"
}
}
Response message
Entity S0.2.481.1.20160326004729982 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.20160326004729982/json

{
"m2m:rsp":
{
"rsc":2000,
"fr": "S0.2.481.1.20160326004729982",
"rqi":"rqi-20160414063014594jn3d"
}

Page-92
Mobius-Yellow Turtle REST APIs

Use Case II: Subscription and notification for device control

Secenario I: Notification-for-device-control

Scenario Name Notification-for-child-create-of-subscribed-to-resource


① Resource Structure

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

We assume there is three entities,


- an AE (an IoT application-A) that initiates a <subscription> resource sub_monitor
create request to the target <container> temp_controller; the request contains
configured notificationURL which is set to a public access URL of a physical
device;
- an AE (IoT application-B) that has access right to create a <contentInstance>
resource under the <container> resource temp_controller;
- the hosting CSE.
Call flows among these three entities are as following:
- The AE (IoT-application-A) sends a a <subscription> resource sub_control create
request to the target <container> temp_controller;
- The AE (IoT-application-B) sends a <contentInstance> create request to the
subscribed-to-resource (<container>) containing the device controlling
command;
- The hosting CSE sends a notification to the target physical device for controlling.

d. IoT-Application-A subscribe to <container> resource


Procedures
① Call flow

Page-93
Mobius-Yellow Turtle REST APIs

AE (IoT-
Mobius-YT
application-A)

Authenticated Subscription create request


User

Response with attribute representation


of the created <subscription> resource

② Resource URL Information


POST /mobius-yt/temp_sensor/temp_controller?rcn=0

③ Http Header Information


Header Value

Accept application/ json


X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=23

④ 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.

Request message example:


POST /mobius-yt/temp_sensor/temp_controller?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req14335
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=23

{
"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
}
}

Example of Response Message


HTTP/1.1 201 Created

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
}
}

e. Creation of child resource of the subscribed-to-<container>

① Call flow
AE (IoT-
Mobius-YT
application-B)

Authenticated Child resource creation of


User the subscribed-to-<container>

Response with no http response body included

② Resource URL Information


POST /mobius-yt/temp_sensor/temp_controller?rcn=0

③ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json?ty=4

④ Example: Create a new <contentInstance> resource under the <container>


resource temp_container. The control command for the device control is contained
as a content of attribute content.

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

f. Hosting CSE sends notification to subscriber

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.

We assume the entity (mobius-yt) has subscribed to Topic /oneM2M/resp/mobius-


yt/+ in order to receive notification acknowledgement while the entity has subscribed to
Topic /oneM2M/req/+/ S1.352.7.0.20170111014729892 in order to receive
notification request from any entity.

① Call flow

Target physical device-A Hosting CSE

Send notification request


containing the control command for the
the target device

② Resource URL information


The hosting CSE PUBLISH notification request associated with Topic
/oneM2M/req/mobius-yt/S1.352.7.0.20170111014729892/json
③ HTTP Header information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
④ Example
Request message
The hosting CSE PUBLISH the notification request message in the payload associated with Topic
/oneM2M/req/mobius-yt/S1.352.7.0.20170111014729892/json
{
"m2m:sgn":
{
"nev":

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"
}
}

2.2.10 <Group> Resource


The <group> resource is defined in the oneM2M specifications for management of a group of resources
with same or different (mixed) type(s). Attribute memberType is defined to specify the type of resources
as the group members. The memberType attribute can be either set to the value of resource type of group
member when all the group members have same resource type or to “MIXED” as a default value
indicating the group members have different resource types. In addition, a mandatory attribute
memberID is defined to identify group members, which can be set to the resourceID of the group
members. Also a mandatory attribute maxNrOfMembers is defined to limit the maximum number of
group members in a group resource. The originator of <group> resource creation request may also set
the value of attribute consistencyStrategy to either ABANDON_GROUP, SET_MIXED, or default
ABANDON_MEMBER to indicate the preference of the originator for handle the <group> resource
creation by hosting CSE when the validation of memberType by hosting CSE is unsuccessful.

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.

Table 2.2.10. 1 Universal Attributes of <group> resource

Attribute Name Request Optionality


Create Update
@resourceName O NP
resourceType NP NP
resourceID NP NP
parentID NP NP
accessControlPolicyID
O O
s
creationTime NP NP
expirationTime O O
lastModifiedTime NP NP
labels O O
announceTo O O
announcedAttribute O O
dynamicAuthorization
O O
ConsultationIDs

Table 2.2.10. 2 Resource Specific Attributes of <group> resource

Page-98
Mobius-Yellow Turtle REST APIs

Attribute Name Request Data Type Default Value and


Optionality Constraints
Create Update
creator O NP m2m:ID
memberType m2m:memberType Default value is set to
O NP
'MIXED'
currentNrOfMembers xs:positiveInteger No default
(This is generated by
the hosting CSE and
NP NP limited by the
maxNrOfMembers
attribute of the
<group> resource)
maxNrOfMembers M O xs:positiveInteger No default
memberIDs M O list of xs:anyURI No default
membersAccessCont list of xs:anyURI
O O No default
rolPolicyIDs
memberTypeValidate xs:boolean No default
d NP NP (This is generated by
the hosting CSE)
consistencyStrategy m2m:consistencyStrate Default value is set to
O NP gy 'ABANDON_MEMBE
R'
groupName O O xs:string No default
1) API-GRP-C

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

External Entity Mobius-YT

Group create request

Response with no http response body included

③ Resource URL Information


POST /mobius-yt/temp_sensor?rcn=0

Page-99
Mobius-Yellow Turtle REST APIs

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=9

⑤ Example of Request Message


POST /mobius-yt/temp_sensor?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req15999
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=9

{
"m2m:grp" : {
"mid": [
"/mobius-yt/temp_sensor/temp_container",
"/mobius-yt/temp_sensor/temp_container02"
],
"mnm": 50,
"mt": 3,
"rn": "temp_group"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Content-Length: 0
Content-Location: /mobius-yt/temp_sensor/temp_group
Content-Type: application/json
X-M2M-RI: req15999
X-M2M-RSC: 2001

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

External Entity Mobius-YT

Group retrieve request

Response with attributes representation


of the requested
<group> resource

⑦ Resource URL Information


GET /mobius-yt/temp_sensor/temp_group?rcn=1

⑧ Http Header Information

Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑨ Example of Request Message


GET /mobius-yt/temp_sensor/temp_group?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req333325
X-M2M-Origin: Cae201623213

⑩ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 322
Content-Type: application/json
X-M2M-RI: req333325
X-M2M-RSC: 2000

{
"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

Target Resource Requested <group> resource


The interface is used to send a <group> update request attached with resultContent set
to 0 to the target <group> resource and receive a successful <group> creation response
with no http response body included.

① Resource Structure

Mobius-yt

temp_sensor

temp_group

② Call Flow

External Entity Mobius-YT

Group update request

Response with no http response body included

③ Resource URL Information


Interface PUT /mobius-yt/temp_sensor/temp_group?rcn=0
Description
④ Http Header Information
Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


PUT /mobius-yt/temp_sensor/temp_group?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req999932
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

{
"m2m:grp" : {
"mnm": 100,
"lbl": ["containers_group"]
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: req999932
X-M2M-RSC: 2004

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

External Entity Mobius-YT

Group delete request

Response with no http response body included

Interface
Description
③ Resource URL Information
DELETE /mobius-yt/temp_sensor/temp_group?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


DELETE /mobius-yt/temp_sensor/temp_group?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
X-M2M-RI: req999332
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
X-M2M-RI: req999332
X-M2M-RSC: 2002

Page-103
Mobius-Yellow Turtle REST APIs

2.2.11 <TimeSeries> Resource


The <timeSeries> resource represents a container for Time Series Data instances. It is used to share information
with other entities and potentially to track, detect and report the missing data in Time Series. A <timeSeries>
resource has no associated content. It has only attributes and child resources.

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.

[3] The accessControlPolicyID and stateTag also applied to <TimeSeries> resource.

but it still has some differences as following:

[4] Mainly designed for storing time series data instances;

[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.

Table 2.2.11-1 Universal/Common Attributes of <timeSeries> resource

Attribute Name Request


Optionality
Create Update
@resourceName O NP
resourceType NP NP
resourceID NP NP
parentID NP NP
accessControlPolicyIDs O O
creationTime NP NP
expirationTime O O
lastModifiedTime NP NP
stateTag NP NP
labels O O
announceTo O O
announcedAttribute O O
creator O NP

Page-104
Mobius-Yellow Turtle REST APIs

Table 2.2.11-2 Resource Specific Attributes of <timeSeries> resource

Attribute Name Request Data Type Default Value and Constraints


Optionality
Create Update
maxNrOfInstances O O xs:nonNegativeInteger No default
maxByteSize O O xs:nonNegativeInteger No default
maxInstanceAge O O xs:nonNegativeInteger No default
currentNrOfInstances xs:nonNegativeInteger No default
NP NP (This is generated by the Hosting
CSE and limited by the
maxNrOfInstances)
currentByteSize xs:nonNegativeInteger No default
NP NP (This is generated by the Hosting
CSE and limited by the
maxByteSize)
periodicInterval O O xs:nonNegativeInteger No default
missingDataDetect O O xs:boolean No default
missingDataMaxNr O O xs:nonNegativeInteger No default
missingDataList m2m:missingDataList No default
NP NP
missingDataCurrentNr xs:nonNegativeInteger No default
(This is generated by the Hosting
NP NP
CSE and limited by the
missingDataMaxNr)
missingDataDetectTimer xs:nonNegativeInteger No default
O O
(This is in units of milliseconds.)
ontologyRef O O xs:anyURI No default

Table 2.2.11-3 Child Resources of <timeSeries> resource

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

External Entity Mobius-YT

timeSeries create request

Response with no http response body included

③ Resource URL Information


POST /mobius-yt/temp_sensor?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=29

⑤ Example of Request Message


POST /mobius-yt/temp_sensor?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req98999
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=29

{
"m2m:ts":
{
"rn": "timeSeries_cnt",
"pei": 1000,
"mdd": true,
"mdt": 200
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Content-Length: 0
Content-Location: /mobius-yt/temp_sensor/timeSeries_cnt
Content-Type: application/json
X-M2M-RI: req98999
X-M2M-RSC: 2001

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

External Entity Mobius-YT

timeSeries retrieve request

Interface Response with attributes representation


Description of the requested
<timeSeries> resource

③ Resource URL Information


GET /mobius-yt/temp_sensor/timeSeries_cnt?rcn=1

④ Http Header Information

Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET /mobius-yt/temp_sensor/timeSeries_cnt?rcn=1 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req399325
X-M2M-Origin: Cae201623213

⑥ Example of Response Message

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

External Entity Mobius-YT

timeSeries update request

Response with no http response body included

③ Resource URL Information

Page-108
Mobius-Yellow Turtle REST APIs

PUT /mobius-yt/temp_sensor/timeSeries_cnt?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


PUT /mobius-yt/temp_sensor/timeSeries_cnt?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req990932
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

{
"m2m:ts":
{
"mdn":200
}
}

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
X-M2M-RI: req990932
X-M2M-RSC: 2004
4) API-TS-D

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

External Entity Mobius-YT

timeSeries delete request

Response with no http response body included

③ Resource URL Information


DELETE /mobius-yt/temp_sensor/timeSeries_cnt?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


DELETE /mobius-yt/temp_sensor/timeSeries_cnt?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
X-M2M-RI: req999332
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

⑥ Example of Response Message


HTTP/1.1 200 OK
Accept: application/json
Content-Length: 0
X-M2M-RI: req999332
X-M2M-RSC: 2002

2.2.12 <timeSeriesInstance> Resource


The <timeSeriesInstance> resource represents a data instance of the <timeSeries> resource. It shares the similar
concept with <contentInstance> and both cannot be modified once created. The creation of the
<timeSeriesInstance> are limited by the policies that applied to it parent <timeSeries> resource in terms of
maxByteSize, maxNrOfInstances, maxInstanceAge attribute etc. The <timeSeriesInstance> resource cannot apply
its own accessControlPolicID but can ineritate the the accessControlPolicyID of its parent resource. Similar rule
of stateTag as <contentInstance> resource applies to <timeSeriesInstance>.

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

Table 2.2.12-1 Universal/Common Attributes of <timeSeriesInstance> resource

Attribute Name Request Optionality


Create
@resourceName O
resourceType NP
resourceID NP
parentID NP
creationTime NP
expirationTime O
lastModifiedTime NP
labels O
announceTo O
announcedAttribute O

Table 2.2.12- 2 Resource Specific Attributes of <timeSeriesInstance> resource

Attribute Name Request Optionality Data Type Default Value and


Create Constraints
dataGenerationTime M m2m:absRelTimestamp No default
content M xs:anySimpleType No default
sequenceNr O xs:nonNegativeInteger No default
1) API-TSI-C

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

External Entity Mobius-YT

timeSeriesInstance create request

Response with no http response body included

③ Resource URL Information


POST /mobius-yt/temp_sensor?timeSeries_cnt?rcn=0

Page-111
Mobius-Yellow Turtle REST APIs

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json; ty=30

⑤ Example of Request Message


POST /mobius-yt/temp_sensor/timeSeries_cnt?rcn=0 HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req108999
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json;ty=30

{
"m2m:tsi":
{
"rn": "timeSeries_instance01",
"dgt": "20170106T152424",
"con": "30"
}
}

⑥ Example of Response Message


HTTP/1.1 201 Created
Content-Length: 0
Content-Location: /mobius-
yt/temp_sensor/timeSeries_cnt/timeSeries_instance01
Content-Type: application/json
X-M2M-RI: req108999
X-M2M-RSC: 2001
2) API-TSI-R

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

External Entity Mobius-YT

timeSeriesInstance retrieve request

Response with attributes representation


of the requested
<timeSeriesInstance> resource

③ Resource URL Information


GET /mobius-
yt/temp_sensor/timeSeries_cnt/timeSeries_instance01?rcn=1

④ Http Header Information

Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator

⑤ Example of Request Message


GET /mobius-
yt/temp_sensor/timeSeries_cnt/timeSeries_instance01?rcn=1
HTTP/1.1
Host: yt.iotmobius.com:7579
Accept: application/json
X-M2M-RI: req309325
X-M2M-Origin: Cae201623213

⑥ Example of Response Message


HTTP/1.1 200 OK
Content-Length: 264
Content-Type: application/json
X-M2M-RI: req309325
X-M2M-RSC: 2000

{
"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

External Entity Mobius-YT

timeSeriesInstance delete request

Interface
Response with no http response body included
Description

③ Resource URL Information


DELETE /mobius-
yt/temp_sensor/timeSeries_cnt/timeSeries_instance01?rcn=0

④ Http Header Information


Header Value
Accept application/ json
X-M2M-RI Request ID of external entity
X-M2M-Origin AE-ID of request originator
Content-Type application/vnd.onem2m-res+json

⑤ Example of Request Message


DELETE /mobius-
yt/temp_sensor/timeSeries_cnt/timeSeries_instance01?rcn=0
HTTP/1.1
Host: yt.iotmobius.com:7579
X-M2M-RI: req979332
X-M2M-Origin: Cae201623213
Content-Type: application/vnd.onem2m-res+json

⑥ Example of Response Message

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

[2] TS-0004 Service_Layer_Core_Protocol

[3] TS-0009 HTTP_Protocol_Binding

[4] TS-0010 MQTT_protocol_binding

[5] TR-0025 Application_Developer_Guide

Page-115

You might also like