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

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 IETF RFC 7230 [1]).

The resource identifier part of the To parameter can be represented in three different forms (see clause 6.2.3 of oneM2M TS-0004 [3] and clause 7.2 of oneM2M TS-0001 [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 of oneM2M TS-0001 [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 "/_".

Table 6.2.2.1‑1 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.

Table 6.2.2.1‑1 : Mapping examples between To parameter and path component of request-line

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 IETF RFC 7230 [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.2‑1 compliant with IETF RFC 7230 [1]. Each applicable request primitive parameters and elements of Filter Criteria parameter shown in table 6.2.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.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 = 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 TS-0004 [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 TS-0004 [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 TS-0004 [3]. Note that the tag of the XML representation is omitted in the HTTP binding.

The 'childAttribute' and 'parentAttribute' elements of the Filter Criteria request primitive are handled in a similar way to the 'attribute' element. Those sequences of attribute elements will be mapped in the query string by adding a prefix to each attribute name respectively: 'c.' for 'childAttribute' and 'p.' for 'parentAttribute'. This results, using the example above, in the mappings as c.attname1=attvalue1&c.attname2=attvalue2 for 'childAttribute', and p.attname1=attvalue1&p.attname2=attvalue2 for 'parentAttribute'.

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

• EXAMPLE 3) Semantic Discovery

  The entity wants to discover resources whose semantic description stored in the descriptor attribute of a <semanticDescriptor> child resource fulfils the semantic filter specified in SPARQL. In this case, the semantic descriptor of the resource to discover has to contain information about a Thing of type Car based on the concept defined in the "myOnt" ontology.
  Due to the use of reserved characters in SPARQL, the semanticsFilter requires "percent-encoding" [9].

  Primitive parameters:
     To:                 /CSE1234/RCSE78
     Filter Criteria:    semanticsFilter =
                         PREFIX rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
                         PREFIX myOnt: http://www.onem2m.org/ontology/myontology#
                         SELECT ?car WHERE { ?car rdf:type myOnt:Car }
     RequestTarget:         /CSE1234/RCSE78?smf=PREFIX%20rdf%3A%20%3Chttp%3A%2F%2Fwww.w3.org%2F1999%2F02%2F22rdfsyntaxns%23%3E%20PREFIX%20myOnt%3A%20%3Chttp%3A%2F%2Fwww.onem2m.org%2Fontology%2Fmyontology%23%3E%20SELECT%20%3Fcar%20WHERE%20%7B%20%3Fcar%20%20rdf%3Atype%20myOnt%3Acar%20%7D

• EXAMPLE 4) Geo-query

  When an application wants to query a resource having its geo-location within the rectangle:

  Primitive parameters:
      To:                /CSE1234/RCSE78
      Filter Criteria:   geometryType = 3                  (Polygon)
                         geometry = [[0.0, 0.0], [0.0, 100.0], [100.0, 100.0], [100.0, 0.0], [0.0, 0.0]]
                         geoSpatialFunction = 1            (Within)
                         filterUsage = discovery
  
  Request-Target:        /CSE1234/RCSE78?fu=1&gmty=3&geom=[[0.0,0.0],[0.0,100.0], [100.0,100.0],[100.0,0.0],[0.0,0.0]]&gsf=1

Note that, in the HTTP Request-Target, longitude and latitude are separated by an empty space and each pair of longitude and latitude are separated by comma.

Any of the short names listed in table 6.2.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 in oneM2M TS-0004 [3] may be used in the query-string in representations of attname=attvalue expressions, except those that shall be omitted (see clause 7.3.3.17.9 in oneM2M TS-0004 [3]).

Table 6.2.2.2‑1: oneM2M request parameters mapped as query-string field

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 Table 6.3.3-1 of TS-0004 [3]) in the Content parameter.

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.

• Case 1 Primitive Example:

  xml version="1.0" encoding="UTF-8"?
   

  HTTP Binding: //example.net/myCSE/-/Cont1?atrl=ri+lbl+rr

• Case 2 Primitive Example:

  xml version="1.0" encoding="UTF-8"?
  

  HTTP Binding: //example.net/myCSE/-/Cont1?atrl=rr

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 oneM2M TS-0004 [3].

6.2.3 HTTP-Version

This specification 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.17).

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.

Table 6.3.2‑1: Status Code Mapping

6.3.3 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 oneM2M TS-0004 [3]. In this case the origin-form of target URI shall be used (see clause 6.2.2).

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", "application/cbor" or the oneM2M defined media types defined in clause 6.7 of oneM2M TS-0004 [3]. Note that some of the oneM2M defined media types defined in clause 6.7 of oneM2M TS-0004 [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 oneM2M TS-0004 [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
               application/vnd.onem2m-res+json; ty=3
               application/vnd.onem2m-res+cbor; ty=3

6.4.4 Content-Location

The Content-Location header of the HTTP response to a Create request shall be set to the URI of the created resource, if this URI is present in the Content parameter of the Create response primitive. See clause 7.3.3.12 "Create a success response" in oneM2M TS-0004 [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 IETF RFC 7232 [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.

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.

6.4.11 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 (e.g. Response Status Code 4000 and 4102 are mapped to HTTP Status Code 400 in the table 6.3.2‑1).

6.4.18 X-M2M-ATI

The X-M2M-ATI header in a HTTP response message shall be mapped to the Assigned Token Identifiers parameter of response primitives and vice versa.

The format of the X-M2M-ATI header shall be represented as a sequence of lti-value:tkid-value pairs separated by a colon ":' and multiple pairs separated by '+' character.

For example, if the XML representation of the Assigned Token Identifiers parameter is given as (using short element names):

the header would look as follows:

X-M2M-ATI: lti-value1:tkid-value1 + lti-value2:tkid-value2 + ...`  

The data type m2m:dynAuthlocalTokenIdAssignments of the Assigned Token Identifiers parameter is defined in clause 6.3.5.43 of TS-0004 [3].

6.4.19 Authorization

If a request primitive includes a Tokens parameter it shall be mapped to the Authorization header.

The Tokens primitive parameter is represented as a space separated list of JSON Web Signature (JWS) and JSON Web Encryption (JWE) strings in Compact Serialization format of datatype m2m:dynAuthJWT as defined in clause 6.3.3 of TS-0004 [3].

When mapped into the Authorization header, each individual token in the Tokens primitive parameter shall be separated by '+' character.

For example, if the Tokens parameter consists of a list of two JWS/JWE Tokens,

eyJ0eXAiOiJK.eyJpc3MiOiJqb2UiLA0KIC.dBjftJeZ4CVP 
eyJ0eXAiOiJK.eyJpc3MiOiJqb2UiLA0KIC.dBjftJeZ4CVP.5eym8TW_c8SuK.SdiwkIr3a.XFBoMYUZo

the Authorization header looks as follows:

Authorization: eyJ0eXAiOiJK.eyJpc3MiOiJqb2UiLA0KIC.dBjftJeZ4CVP+ eyJ0eXAiOiJK.eyJpc3MiOiJqb2UiL
               A0KIC.dBjftJeZ4CVP.5eym8TW\_c8SuK.SdiwkIr3a.XFBoMYUZo

The line break in the above example is for illustrative purposes and shall not be included into the Authorization header.

6.4.20 X-M2M-CTS

The X-M2M-CTS header shall be mapped to the Content Status parameter of response primitives and vice versa, if applicable.

6.4.21 X-M2M-CTO

The X-M2M-CTO header shall be mapped to the Content Offset parameter of response primitives, and vice versa, if applicable.

6.4.22 X-M2M-RVI

The X-M2M-RVI header shall be mapped to the Release Version Indicator parameter of request and response primitives, and vice versa.

6.4.23 X-M2M-VSI

The X-M2M-VSI header shall be mapped to the Vendor Information parameter of request and response primitives, and vice versa.

6.4.24 X-M2M-AS

If a request primitive includes an Authorization Signatures parameter, it shall be mapped to the X-M2M-AS header.

The Authorization Signatures primitive parameter is represented as a space separated list of URL-safe base64 encoded (base64url)) strings of datatype m2m:signatureList as defined in clause 6.3.3 of TS-0004 [3].

When mapped into the X-M2M-AS header, each individual signature in the Authorization Signatures primitive parameter shall be separated by '+' character.

For example, if the Authorization Signatures parameter consists of a list of two elements,

i6watmQQQ1y3GB-VsWq5fJKzQcBB4jRfH1bfJFj0JtFVtLotttzYyA==
IWijxQjUrcXBYoCei4QxjWo9Kg8D3p9tlWoT4t0_gyTE96639In0FZFY2_rvP-_bMJ01EArmKZsR5VW3rwoPxw==

the X-M2M-AS header looks as follows:

X-M2M-AS: i6watmQQQ1y3GB-VsWq5fJKzQcBB4jRfH1bfJFj0JtFVtLotttzYyA==+ 
          IWijxQjUrcXBYoCei4QxjWo9Kg8D3p9tlWoT4t0_gyTE96639In0FZFY2_rvP-_bMJ01EarmKZsR5VW3rwoPxw==

The line break in the above example is for illustrative purposes and shall not be included into the X-M2M-AS header. Whitespace characters are insignificant and should not be included into the header.

6.4.25 X-M2M-ASRI

The X-M2M-ASRI header in a HTTP response message shall be mapped to the Authorization Signature Request Information parameter of response primitives and vice versa, if applicable.

6.4.26 X-M2M-OMR

The X-M2M-OMR header shall be mapped to the Ontology Mapping Resources parameter of request primitives and vice versa, if applicable. The format of the oneM2M-OMR header shall be represented as a sequence of oneM2M resource identifiers separated by a '+'.

EXAMPLE: The header looks as follows:

oneM2M-OMR: /IN-CSE-0001/omr1+/IN-CSE-0001/omr2+...

6.4.27 X-M2M-MSU

The X-M2M-MSU header shall be mapped to the M2M Service User parameter of request and response primitives, and vice versa, if applicable.

6.4.28 X-M2M-PRPI

The X-M2M-PRPI header shall be mapped to the Primitive Profile Identifier parameter of request 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 with the following exceptions:

1. For partial Retrieve request primitives. Attributes contained in the Content parameter of Retrieve request primitive shall be mapped to the fragment component of request-target, as specified in clause 6.2.2.2, and vice versa.
2. A Token Request Information parameter included in a response primitive shall be mapped into the message-body either as a XML or JSON serialized object. The Content-Type and Content-Length headers shall be set compliant with the data representation (i.e. Content-Type: application/xml or application/json depending on the serialization format). Note that the Token Request Information parameter is used in oneM2M error response primitives (X-M2M-RSC: 4103 "ORIGINATOR_HAS_NO_PRIVILEGE") only, which do not carry any other primitive content.

Error response messages which include the Token Request Information parameter in the Message-Body shall not include any debugging information.

6.6 Message Routing

HTTP request and response message routing shall be performed as described in HTTP/1.1 [1].

6.7 Ignoring HTTP Responses for Notifications to non-oneM2M Entitites

In TS-0004 [3], clause 7.3.1.3 specifies that an originator shall not wait for the Response primitive from the receiver after sending a Notification request to a non-oneM2M entity. If such a Notification is delivered through the CSE’s HTTP binding then the HTTP response message from the Notification’s receiver shall be ignored.