ETSI TS 118 109 V1.1.0 (2016-03)
TECHNICAL SPECIFICATION
oneM2M;
HTTP Protocol Binding
(oneM2M TS-0009 version 1.5.1 Release 1)
oneM2M TS-0009 version 1.5.1 Release 1
2
ETSI TS 118 109 V1.1.0 (2016-03)
Reference
RTS/oneM2M-000009v110
Keywords
IoT,M2M,PROTOCOL
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88
Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the only prevailing document is the
print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.
© European Telecommunications Standards Institute 2016.
All rights reserved.
DECTTM, PLUGTESTSTM, UMTSTM and the ETSI logo are Trade Marks of ETSI registered for the benefit of its Members.
3GPPTM and LTE™ are Trade Marks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
GSM® and the GSM logo are Trade Marks registered and owned by the GSM Association.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
3
ETSI TS 118 109 V1.1.0 (2016-03)
Contents
Intellectual Property Rights ................................................................................................................................5
Foreword.............................................................................................................................................................5
1
Scope ........................................................................................................................................................6
2
References ................................................................................................................................................6
2.1
2.2
Normative references ......................................................................................................................................... 6
Informative references ........................................................................................................................................ 6
3
Abbreviations ...........................................................................................................................................7
4
Conventions ..............................................................................................................................................7
5
Overview on HTTP Binding ....................................................................................................................7
5.1
5.2
5.3
6
Introduction ........................................................................................................................................................ 7
Request-Line ...................................................................................................................................................... 8
Status-Line ......................................................................................................................................................... 8
HTTP Message Mapping..........................................................................................................................8
6.1
Introduction ........................................................................................................................................................ 8
6.2
Parameter Mappings on Request-Line ............................................................................................................... 9
6.2.1
Method .......................................................................................................................................................... 9
6.2.2
Request-Target .............................................................................................................................................. 9
6.2.2.1 Path component ...................................................................................................................................................... 9
6.2.2.2 Query component ................................................................................................................................................. 10
6.2.3
HTTP-Version ............................................................................................................................................ 12
6.3
Status-Line ....................................................................................................................................................... 12
6.3.1
HTTP-Version ............................................................................................................................................ 12
6.3.2
Status-Code ................................................................................................................................................. 12
6.3.3
Reason-Phrase............................................................................................................................................. 13
6.4
Header Fields.................................................................................................................................................... 13
6.4.0
Introduction................................................................................................................................................. 13
6.4.1
Host ............................................................................................................................................................. 13
6.4.2
Accept ......................................................................................................................................................... 14
6.4.3
Content-Type .............................................................................................................................................. 14
6.4.4
Content-Location ........................................................................................................................................ 14
6.4.5
Content-Length ........................................................................................................................................... 14
6.4.6
Etag ............................................................................................................................................................. 14
6.4.7
X-M2M-Origin ........................................................................................................................................... 14
6.4.8
X-M2M-RI .................................................................................................................................................. 14
6.4.9
Void ............................................................................................................................................................ 14
6.4.10
X-M2M-GID............................................................................................................................................... 14
6.4.11
X-M2M-RTU .............................................................................................................................................. 15
6.4.12
X-M2M-OT ................................................................................................................................................ 15
6.4.13
X-M2M-RST .............................................................................................................................................. 15
6.4.14
X-M2M-RET .............................................................................................................................................. 15
6.4.15
X-M2M-OET .............................................................................................................................................. 15
6.4.16
X-M2M-EC................................................................................................................................................. 15
6.4.17
X-M2M-RSC .............................................................................................................................................. 15
6.5
Message-body................................................................................................................................................... 15
6.6
Message Routing .............................................................................................................................................. 15
7
7.1
7.2
Security Consideration ...........................................................................................................................15
Authentication on HTTP Request Message...................................................................................................... 15
Transport Layer Security .................................................................................................................................. 16
Annex A (informative):
A.1
Example Procedures ......................................................................................17
<container> resource creation ................................................................................................................17
Annex B (informative):
WebSocket ......................................................................................................18
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
B.1
4
ETSI TS 118 109 V1.1.0 (2016-03)
Notification using WebSocket................................................................................................................18
History ..............................................................................................................................................................19
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
5
ETSI TS 118 109 V1.1.0 (2016-03)
Intellectual Property Rights
IPRs essential or potentially essential to the present document may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (https://ipr.etsi.org/).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Foreword
This Technical Specification (TS) has been produced by ETSI Partnership Project oneM2M (oneM2M).
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
1
6
ETSI TS 118 109 V1.1.0 (2016-03)
Scope
The present document will cover the protocol specific part of communication protocol used by oneM2M compliant
systems as RESTful HTTP binding.
The scope of the present document is (not limited to as shown below):
•
Binding oneM2M Protocol primitive types to HTTP method.
•
Binding oneM2M response status codes (successful/unsuccessful) to HTTP response codes.
•
Binding oneM2M RESTful resources to HTTP resources.
The present document is depending on Core Protocol specification (ETSI TS 118 104) for data types.
2
References
2.1
Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
The following referenced documents are necessary for the application of the present document.
[1]
IETF RFC 7230 (June 2014): “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and
Routing”.
[2]
ETSI TS 118 103: "oneM2M; Security Solutions (oneM2M TS-0003)".
[3]
ETSI TS 118 104: “oneM2M; Service Layer Core Protocol Specification (oneM2M TS-0004)”.
[4]
RFC7235: “Hypertext Transfer Protocol (HTTP/1.1): Authentication”, IETF, June 2014.
[5]
RFC6750: “The Oauth 2.0 Authorization Framework: Bearer Token Usage”, October 2012.
[6]
ETSI TS 118 111: "oneM2M; Common Terminology (oneM2M TS-0011)".
[7]
ETSI TS 118 101: "oneM2M; Functional Architecture (oneM2M TS-0001)".
[8]
IETF RFC 7232 (June 2014): “Hypertext Transfer Protocol (HTTP/1.1): “Conditional Requests”.
2.2
Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area.
[i.1]
NOTE:
[i.2]
oneM2M Drafting Rules.
Available at http://www.onem2m.org/images/files/oneM2M-Drafting-Rules.pdf.
IETF RFC 6455 (December 2011):”The WebSocket Protocol”.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
3
7
ETSI TS 118 109 V1.1.0 (2016-03)
Abbreviations
For the purposes of the present document, the following abbreviations and those given in ETSI TS 118 111-Common
Terminology [6] apply:
AE
CSE
CSE-ID
HTTP
IN-CSE
TLS
MN-CSE
URI
4
Application Entity
Common Services Entity
Common Service Entity Identifier
Hyper Text Transfer Protocol
Infrastructure Node – Common Services Entity
Transport Layer Security
Middle Node – Common Services Entity
Uniform Resource IdentifierXML eXtensible Markup Language
Conventions
The keywords “Shall”, “Shall not”, “May”, “Need not”, “Should”, “Should not” in this document are to be interpreted
as described in the oneM2M Drafting Rules [i.1].
5
Overview on HTTP Binding
5.1
Introduction
HTTP binding specifies the equivalence between oneM2M request and response primitives and HTTP request and
response messages, respectively. This clause provides a brief overview on the mapping relationship between oneM2M
and HTTP message parameters.
This clause describes how oneM2M request/response primitives can be mapped to HTTP request/response messages
and vice versa.
Figure 5.1-1 illustrates an example oneM2M system configuration and its correspondence to an HTTP-based
information system if HTTP binding as defined in the present document is applied. The upper diagram in Figure 5.1-1
shows with solid line arrows the flow of a request primitive originating from an AE which is registered to an MN-CSE
(Registrar of AE). The request primitive is assumed to address a resource which is hosted by another MN-CSE (Host of
Resource). Both MN-CSEs are registered to the same IN-CSE.
When applying HTTP binding, the oneM2M entities of the upper diagram take the roles outlined in the lower diagram
of a corresponding HTTP information system as defined in [1]. The AE takes the role of an HTTP client, the MN-CSE
(Registrar of AE) takes the role of a HTTP Proxy Server, and both the IN-CSE and MN-CSE (Host of Resource) take
the role of a HTTP server for this particular request message.
CSEs may also issue unsolicited request messages, shown with dashed line arrows in Figure 5.1-1, and receive
associated response messages. Therefore, for HTTP protocol binding, CSEs generally provides capability of both HTTP
Server and HTTP Client. Aes may provide HTTP Server capability optionally in order to be able to serve Notification
request messages (see ETSI TS 118 104 [3] and ETSI TS 118 101 [7]).
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
8
ETSI TS 118 109 V1.1.0 (2016-03)
Figure 5.1-1 : Correspondence between oneM2M entities and HTTP Client and Server
Each individual request primitive will be mapped to single HTTP request message, and each individual response
primitive will be mapped to a single HTTP response message, and vice-versa.
An HTTP request message consists of Request-Line, headers and message-body. An HTTP response message consists
of Status-Line, headers and message-body [1]. HTTP header names are case-insensitive and a Receiver shall accept
headers that are either lower or upper or any mixture thereof. This clause describes how oneM2M request/response
primitives are mapped to HTTP messages at a high level. Corresponding details are specified in clause 6.
5.2
Request-Line
The HTTP method of a request message is mapped to the Operation parameter, and vice-versa.
At the message originator side the HTTP Request-Target is derived from the To parameter of the request primitive,
including a query string which carries other specific primitive parameters.
HTTP-Version is specified in clause 6.
5.3
Status-Line
HTTP Version is specified in clause 6.
The Status-Code of HTTP response messages is derived from the Response Status Code parameter of the response
primitive. The Reason-Phrase is not applicable to oneM2M systems and is omitted.
6
HTTP Message Mapping
6.1
Introduction
Mapping between oneM2M primitives and HTTP messages shall be applied in the following four use cases:
1.
Mapping of request primitive to HTTP request message at the request originator (HTTP client)
2.
Mapping of HTTP request message to request primitive at the request receiver (HTTP server)
3.
Mapping of response primitive to HTTP response message at the request receiver (HTTP server)
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
4.
9
ETSI TS 118 109 V1.1.0 (2016-03)
Mapping of HTTP response message to response primitive at the request originator (HTTP client)
All four use cases also appear at transit CSEs.
The following clauses specify the mapping between each oneM2M primitive parameter and a corresponding HTTP
message field to compose a HTTP request/response message.
6.2
Parameter Mappings on Request-Line
6.2.1
Method
The HTTP ‘Method’ shall be derived from the Operation request primitive parameter of the request primitive.
Table 6.2.1-1: HTTP Method Mapping
oneM2M Operation
Create
Retrieve
Update
Delete
Notify
HTTP Method
POST
GET
PUT
DELETE
POST
At the Receiver, an HTTP request message with POST method shall be mapped either to a Create or Notify Operation
parameter. Discrimination between Create and Notify operations can be accomplished by inspection of the content-type
header. The Resource Type parameter is present in the content-type header only when the HTTP POST request
represents a Create request (see clause 6.4.3). The Resource Type parameter is not present in the content-type header
when the HTTP POST request represents a Notify request.
6.2.2
Request-Target
6.2.2.1 Path component
The path component of the origin-form HTTP Request-Target shall be interpreted as the mapping of the resource
identifier part of the To request primitive parameter. If the HTTP message is sent directly to the next hop CSE, the
origin-form of Request-Target shall be employed (see clause 5.3.1 of [1]).
The resource identifier part of the To parameter can be represented in three different forms (see clause 6.2.3 [3] and
clause 7.2 [7]):
•
CSE-Relative-Resource-ID,
•
SP-Relative-Resource-ID,
•
Absolute-Resource-ID.
Each of the above three formats may include either a structured Resource ID (used for hierarchical addressing) or an
unstructured Resource ID (used for non-hierarchical addressing) as defined in clause 7.2 [7].
For CSE-relative Resource ID representation, the path component of the HTTP request message shall be constructed as
the concatenation of the literal “/” and the To request primitive parameter. For SP-relative Resource ID representation,
the path component of the HTTP request message shall be constructed as the concatenation of the literal “/~” and the To
request primitive parameter. For Absolute Resource ID representation, the path component of the HTTP request
message shall be constructed by replacing the first “/” character of the To request primitive parameter with “/_”.
The Table below shows valid mappings between the To request primitive parameter and the path component of the
origin-form HTTP request target. In the shown examples, /myCSEID and /CSE178 represent applicable CSI-IDs,
CSEBase represents the resource name of a <CSEBase> resource, CSEBase/ae12/cont27/contInst696 represents a
structured CSE-relative resource ID, and cin00856 an unstructured CSE-relative resource ID.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
10
ETSI TS 118 109 V1.1.0 (2016-03)
Table 6.2.2.1-1: Mapping examples between To parameter and path component of request-line
Resource-ID Type
To parameter value
path component (origin-form)
structured CSERelative
CSEBase/ae12/cont27/contInst696
/CSEBase/ae12/cont27/contInst696/
unstructured CSERelative
cin00856
/cin00856
structured SPRelative
/CSE178/CSEBase/ae12/cont27/contInst696
/~/CSE178/CSEBase/ae12/cont27/contInst696
unstructured SPRelative
/CSE178/cin00856
/~/CSE178/cin00856
structured Absolute
//mym2msp.org/CSE178/CSEBase/
ae12/cont27/contInst696
/_/mym2msp.org/CSE178/CSEBase/
ae12/cont27/contInst696
unstructured Absolute
//mym2msp.org/CSE178/cin00856
/_/mym2msp.org/CSE178/cin00856
At the HTTP server side, the reverse operations shall be applied to the path component of request-line to derive a
replica of the original To request primitive parameter.
If the HTTP message is sent to a HTTP proxy instead directly to the next hop CSE, the absolute-form of Request-Target
shall be employed (see clause 5.3.2 of [1]). The absolute-form is derived by prefixing the origin-form with the schema
and the host address of the next hop CSE:
http://{host address of next hop CSE}{origin-form path-component}
6.2.2.2 Query component
The query component (e.g. query-string) may include the optional primitive parameters listed in Table 6.2.2-1
compliant with RFC 7230 [1]. Each applicable request primitive parameters and elements of Filter Criteria parameter
shown in Table 6.2.2-1 shall be represented as pair of field-name and value in query-string. Multiple such pairs shall be
concatenated with an ampersand ‘&’ character used as separator between two pairs.
Table 6.2.2-1 also shows the permitted multiplicity of occurrence of field names in the query-string. Multiplicity ‘0..1’
means that a parameter is optional and can occur at most once. Parameters with multiplicity ‘0..n’, may occur multiple
times in the query-string in the form of <query field name> = value. For example, if the resourceType element of the
Filter Criteria parameter is represented by a list of 3 values ‘2 3 4’ (see clause 6.3.4.7 in ETSI TS 118 104 [3]), it
would be mapped to ty=2+3+4 in the query-string. At the receiver side, this query string can be reverted back into the
list type of representation. The same representation shall be applied for multiple occurrences of contentType and labels
elements.
The ‘attribute’ element of the Filter Criteria request primitive parameter consists of two elements, name and value,
which in XML notation would look for example as follows in case of multiplicity 2 (see clause 6.2.4.8 in ETSI
TS 118 104 [3]):
<attribute>
<name>attname1</name>
<value>attvalue1</value>
</attribute>
<attribute>
<name>attname2</name>
<value>attvalue2</value>
</attribute>
Each name (e.g. attname1 and attname2) shall represent a valid resource attribute name of the resource types indicated
in the ty field of the query-string. The sequence of attribute elements as shown in the above example will be mapped
into the query-string as attname1=attvalue1&attname2=attvalue2. The attribute names (i.e. attname1 and attname2 in
the above example) shall be expressed in the form of short names as defined in clause 8.2.3 of ETSI TS 118 104 [3].
Note that the <attribute> tag of the XML representation is omitted in the HTTP binding.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
11
ETSI TS 118 109 V1.1.0 (2016-03)
Examples of valid Request-Target representations are the following:
Example 1): Request-Target for ‘nonBlockingRequestSynch’
Primitive parameters:
To:
/CSE1234/RCSE78/container234
(SP-Relative-Resource-ID)
Response Type:
responseType = 1
(nonBlockingRequestSynch)
Result Persistence: P1Y2M3DT10H1M0S Request-Target:
/CSE1234/RCSE78/container234?rt=1&rp=P1Y2M3DT10H1M0S
Example 2): Request-Target for Discovery
When the entity wants to discover container resources where the creator attribute has the value ‘Sam’:
Primitive parameters:
To:
/CSE1234/RCSE78
Filter Criteria:
resourceType = 3
(container)
attribute name: creator
attribute value: Sam
filterUsage = discovery
Request-Target:
/CSE1234/RCSE78?ty=3&cr=Sam&fu=1
Any of the short names listed in Table 6.2.2-1, with the exception of ‘atr’, may be used in the query-string. The short
name ‘atr’ itself is not used. Instead, any of the resource attribute short names as listed in Tables 8.2.3-1 to 8.2.3-5 may
be used in the query-string in representations of attname=attvalue expressions, except those that shall be omitted (see
clause 7.2.3.16.9 in [3]).
Table 6.2.2-1: oneM2M request parameters mapped as query-string field
Request Primitive Parameter
Response Type
Result Persistence
Result Content
Delivery Aggregation
createdBefore
createdAfter
modifiedSince
unmodifiedSince
stateTagSmaller
stateTagBigger
expireBefore
expireAfter
labels
resourceType
sizeAbove
sizeBelow
contentType
limit
attribute
filterUsage
Discovery Result Type
Query Field
Name
rt
Multiplicity
rp
rc
da
crb
cra
ms
us
sts
stb
exb
exa
lbl
ty
sza
szb
cty
lim
atr
fu
drt
0..1
0..1
0..1
0..1
0..1
0..1
0..1
0..1
0..1
0..1
0..1
0..n
0..n
0..1
0..1
0..n
0..1
0..n
0..1
0..1
0..1
Note
responseType element of data type
responseTypeInfo (cf. clause 6.3.4.29 of
ETSI TS 118 104 [3])
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
filterCriteria condition
For partial Retrieve request primitives, the To parameter may include the name of a single attribute separated by a ‘#’
character from the resource ID. If multiple resource attributes are to be retrieved with a partial retrieve request
primitive, these attributes are included in form of an attributeList object (as specified in clause 6.3.4.9 of ETSI
TS 118 104 [3] with empty values) in the Content parameter.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
12
ETSI TS 118 109 V1.1.0 (2016-03)
In both cases, the short resource attribute name(s) shall be included into the fragment component of request-target, i.e. it
shall follow any required query-string separated by ‘#’ character. If more than a single attribute name is included into
the fragment component, these shall be separated by a ‘+’ character.
For example, if three resource attributes with long names resourceID, labels and requestReachability are indicated in the
Content primitive parameter, the query component atrl=ri+lbl+rr is attached to the request-target. In case just a single
attribute “rr” is indicated in the To parameter separated by ‘#’ character, the query component atrl=rr is attached to the
request-target. The ‘#’ character and following attribute name shall be omitted from the path component of the request
line.
At the HTTP server side, the reverse operation shall take place, when constructing the retrieve request primitive from
the receive HTTP request message. Single attribute names in the query component may either be mapped back into the
To parameter following a ‘#’ character, or included into the Content parameter using the attributeList format with just a
single list element included. Multiple attributes shall be included into the Content parameter as specified in [3].
6.2.3
HTTP-Version
The present document defines binding compliant with HTTP 1.1 [1]. The HTTP version field in HTTP request
messages shall be set to “HTTP/1.1”.
6.3
Status-Line
6.3.1
HTTP-Version
The HTTP version field in HTTP response messages shall be set to “HTTP/1.1”.
6.3.2
Status-Code
The Response Status Code parameter of response primitives shall be mapped to the HTTP Status-Code. Since the
Response Status Code parameter values have been defined with more detailed information than HTTP status codes, one
or more Response Status Code value may be mapped to the same HTTP Status-Code. The original Response Status
Code parameter value shall be carried in the X-M2M-RSC header(see clause 6.4.14).
The mapping of Response Status Code parameter value of oneM2M request primitive to Status-Code of HTTP request
messages is specified in Table 6.3.2-1.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
13
ETSI TS 118 109 V1.1.0 (2016-03)
Table 6.3.2-1: Status Code Mapping
oneM2M Response Status Codes
1000 (ACCEPTED)
2000 (OK)
2001 (CREATED)
4000 (BAD_REQUEST)
4004 (NOT_FOUND)
4005 (OPERATION_NOT_ALLOWED)
4008 (REQUEST_TIMEOUT)
4101 (SUBSCRIPTION_CREATOR_HAS_NO_PRIVILEGE)
4102 (CONTENTS_UNACCEPTABLE)
4103 (ACCESS_DENIED)
4104 (GROUP_REQUEST_IDENTIFIER_EXISTS)
4105 (CONFLICT)
5000 (INTERNAL_SERVER_ERROR)
5001 (NOT_IMPLEMENTED)
5103 (TARGET_NOT_REACHABLE)
5105 (NO_PRIVILEGE)
5106 (ALREADY_EXISTS)
5203 (TARGET_NOT_SUBSCRIBABLE)
5204 (SUBSCRIPTION_VERIFICATION_INITIATION_FAILED)
5205 (SUBSCRIPTION_HOST_HAS_NO_PRIVILEGE)
5206 (NON_BLOCKING_REQUEST_NOT_SUPPORTED)
5207 (NOT_ACCEPTABLE)
6003 (EXTERNAL_OBJECT_NOT_REACHABLE)
6005 (EXTERNAL_OBJECT_NOT_FOUND)
6010 (MAX_NUMBER_OF_MEMBER_EXCEEDED)
6011 (MEMBER_TYPE_INCONSISTENT)
6020 (MANAGEMENT_SESSION_CANNOT_BE_ESTABLISHED)
6021 (MANAGEMENT_SESSION_ESTABLISHMENT_TIMEOUT)
6022 (INVALID_CMDTYPE)
6023 (INVALID_ARGUMENTS)
6024 (INSUFFICIENT_ARGUMENT)
6025 (MGMT_CONVERSION_ERROR)
6026 (CANCELLATION_FAILED)
6028 (ALREADY_COMPLETE)
6029 (COMMAND_NOT_CANCELLABLE)
6.3.3
HTTP Status Codes
202 (Accepted)
200 (OK)
201 (Created)
400 (Bad Request)
404 (Not Found)
405 (Method Not Allowed)
408 (Request Timeout)
403 (Forbidden)
400 (Bad Request)
403 (Forbidden)
409 (Conflict)
409 (Conflict)
500 (Internal Server Error)
501 (Not Implemented)
404 (Not Found)
403 (Forbidden)
403 (Forbidden)
403 (Forbidden)
500 (Internal Server Error)
403 (Forbidden)
501 (Not Implemented)
406 (Not Acceptable)
404 (Not Found)
404 (Not Found)
400 (Bad Request)
400 (Bad Request)
500 (Internal Server Error)
500 (Internal Server Error)
400 (Bad Request)
400 (Bad Request)
400 (Bad Request)
500 (Internal Server Error)
500 (Internal Server Error)
400 (Bad Request)
400 (Bad Request)
Reason-Phrase
The Reason-Phrase shall be omitted in HTTP response messages.
6.4
Header Fields
6.4.0
Introduction
The header fields listed in this clause shall be supported by all entities of the oneM2M system when using HTTP
binding. Any other unrecognized HTTP headers shall be ignored by the HTTP client and server.
6.4.1
Host
The Host header shall be present in each HTTP request message.
While the Request-Target indicates a target resource on the Hosting CSE, the Host header indicates the FQDN or IP
address of the Receiver CSE of the next hop in multi-hop communication scenarios. Therefore, the Request-Target is
not changed but the Host header is changed each time when a request is forwarded to the next hop CSE.
When no HTTP proxy is used, the Host header shall be set as one of the pointOfAccess attribute values of the
Receiver(i.e. pointOfAccess attribute of the corresponding <remoteCSE> resource). Selection of the appropriate
Receiver is described in ETSI TS 118 104 [3]. In this case the origin-form of target URI shall be used (see clause 6.2.2).
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
14
ETSI TS 118 109 V1.1.0 (2016-03)
If the HTTP request message is sent to a HTTP proxy rather than to the next hop CSE, the Host header shall be set to
the FQDN or IP address of the proxy. In this case the absolute-form of target URI shall be used (see clause 6.2.2).
6.4.2
Accept
The Originator may use the Accept header to indicate which media types are acceptable for the response. The Accept
header shall be mapped to a set of media types among “application/xml”, “application/json”, or the oneM2M defined
media types defined in clause 6.7 of [3]. Note that some of the oneM2M defined media types defined in clause 6.7 of
[3] are not applicable for the response. Note that this information is not included in a request primitive.
6.4.3
Content-Type
Any HTTP request or response containing message-body shall include the Content-type header set to one of
“application/xml”, “application/json”, or the oneM2M defined media types defined in clause 6.7 of [3]..
Content-Type of the HTTP response should be chosen by the Hosting CSE considering the Accept header given in the
HTTP request.
The value of the Resource Type primitive parameter, which is present in Create request primitives only, shall be
appended to the Content-type of the corresponding HTTP request message in the form ty=value, separated by a
semicolon character. A valid Content-Type header in this case looks e.g. as follows:
Content-Type: application/vnd.onem2m-res+xml; ty=3
6.4.4
Content-Location
The Content-Location header of HTTP response messages shall be set to the URI of the created resource, when
responding to a Create request primitive. The URI shall be retrieved from the Content parameter of the response
primitive. See clause 7.2.3.11 “Create a success response” in [3].
6.4.5
Content-Length
If message-body is included into HTTP request or response messages, the Content-Length header shall be included
indicating the length of the message-body in octets (8-bit bytes).
6.4.6
Etag
A response primitive sent in reply to a resource retrieval request primitive should include an Etag header [8] in
combination with the resource representation in the HTTP message body.
Etag facilitates the use of conditional requests (i.e. using the if-match and if-none-match HTTP headers) [8].
If a CSE supports the Etag header, then the CSE shall support conditional requests compliant with [8].
6.4.7
X-M2M-Origin
The X-M2M-Origin header shall be mapped to the From parameter of request and response primitives and vice versa, if
applicable.
The X-M2M-Origin header value shall be assigned by the Originator of the request (e.g. AE or CSE).
6.4.8
X-M2M-RI
The X-M2M-RI header shall be mapped to the Request Identifier parameter of request and response primitives and vice
versa.
6.4.9
Void
6.4.10
X-M2M-GID
The X-M2M-GID header shall be mapped to the Group Request Identifier parameter of request primitives and vice
versa, if applicable.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
6.4.11
15
ETSI TS 118 109 V1.1.0 (2016-03)
X-M2M-RTU
The X-M2M-RTU header shall be mapped to the notificationURI element of the Response Type parameter of request
primitives and vice versa, if applicable. If there are more than one value in the element, then the values shall be
combined with “&” character.
6.4.12
X-M2M-OT
The X-M2M-OT header shall be mapped to the Originating Timestamp parameter of request and response primitives,
and vice versa, if applicable.
6.4.13
X-M2M-RST
The X-M2M-RST header shall be mapped to the Result Expiration Timestamp parameter of request and response
primitives, and vice versa, if applicable.
6.4.14
X-M2M-RET
The X-M2M-RET header shall be mapped to the Request Expiration Timestamp parameter of request primitives and
vice versa, if applicable.
6.4.15
X-M2M-OET
The X-M2M-OET header shall be mapped to the Operation Execution Time parameter of request primitives and vice
versa, if applicable.
6.4.16
X-M2M-EC
The X-M2M-EC header shall be mapped to the Event Category parameter of request and response primitives, and vice
versa, if applicable.
6.4.17
X-M2M-RSC
The X-M2M-RSC header in a HTTP response message shall be mapped to the Response Status Code parameter of
response primitives and vice versa.
6.5
Message-body
Message-body shall be mapped to the Content parameter of request and response primitives, and vice versa, if
applicable. This applies to the Content parameter of all primitives, except for partial Retrieve request primitives.
Attributes contained in a Retrieve request primitive shall be mapped to the fragment component of request-target, as
specified in clause 6.2.2.3, and vice versa.
6.6
Message Routing
HTTP request and response message routing shall be performed as described in HTTP/1.1 [1].
7
Security Consideration
7.1
Authentication on HTTP Request Message
When sending the credential to be checked by the Registrar CSE, Proxy-Authorization header should be used as
specified in HTTP/1.1 (see [4]).
When sending the credential to be checked by Hosting CSE, Authorization header should be used as specified in
HTTP/1.1 [4].
When the credential to be checked by Hosting CSE is an Access Token which is compatible with Oauth 2.0 framework
(see [5]), the Bearer authentication scheme shall be used as specified in Oauth 2.0 framework.
NOTE:
The oneM2M Security Solutions [2] does not provide any details on usage or provisioning of the token.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
7.2
16
ETSI TS 118 109 V1.1.0 (2016-03)
Transport Layer Security
oneM2M primitive parameters contained in HTTP messages may be protected by TLS in a hop-by-hop manner. For the
details, see the oneM2M Security Solutions specification [2]
NOTE:
Some provisioning schemes of ETSI TS 118 103 [2] enable the provisioning of end-to-end credentials,
but protocols to establish security associations between non-adjacent nodes are not addressed.by oneM2M
in the present release.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
17
ETSI TS 118 109 V1.1.0 (2016-03)
Annex A (informative):
Example Procedures
A.1
<container> resource creation
Figure A.1-1 is HTTP mapping of procedure described in clause 7.4.7.2.1 [3]. Note the example shown in the figure
applies under the following assumptions:
•
“CSE1” is the name (i.e. value of the resourceName attribute) of the <CSEBase> resource of the registrar CSE
•
“cont1” is the name of the created <container> resource chosen by the registrar CSE
Originator
(ASN-AE)
Registrar CSE
(ASN-CSE)
Step 1: AE requests to create a
<container> resource at ASN-CSE
POST /CSE1?rc=0 HTTP/1.1
Host: 192.168.0.2
X-M2M-Origin: CAE1
X-M2M-RI: 0001
Content-Type: application/vnd.onem2m-res+xml; ty=3
Content-Length: 32
<m2m:cnt><mni>10</mni></m2m:cnt>
Step 2: Local Processing
Process the request and
create "cont1" resource
Step 3: CSE responses OK
HTTP/1.1 201
X-M2M-RI: 0001
Content-Location: /CSE1/cont1
Content-Lengh: 0
Figure A.1-1: oneM2M HTTP Binding Example – container creation
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
18
ETSI TS 118 109 V1.1.0 (2016-03)
Annex B (informative):
WebSocket
B.1
Notification using WebSocket
WebSocket [i.4] can be used for transporting notifications to an AE/CSE. This can be useful for an AE/CSE which is
not server-capable or cannot be reachable for delivery of unsolicited requests.
For example, when an AE needs to receive a notification message from the CSE, the AE establishes a WebSocket
connection to a CSE. When a new notification message is generated, the notification will be sent to the AE as the data
frame of the WebSocket.
ETSI
oneM2M TS-0009 version 1.5.1 Release 1
19
History
Document history
V1.0.0
February 2015
Publication
V1.1.0
March 2016
Publication
ETSI
ETSI TS 118 109 V1.1.0 (2016-03)