Skip to content

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 HTTP Method
Create POST
Retrieve GET
Update PUT
Delete DELETE
Notify 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 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

Resource-ID Type

To parameter value

path component (origin-form)

structured CSE-Relative

CSEBase/ae12/cont27/contInst696

/CSEBase/ae12/cont27/contInst696/

unstructured CSE-Relative

cin00856

/cin00856

structured SP-Relative

/CSE178/CSEBase/ae12/cont27/contInst696

/~/CSE178/CSEBase/ae12/cont27/contInst696

unstructured SP-Relative

/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 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 <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 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 <attribute> 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

Request Primitive Parameter

Query Field Name

Multiplicity

Note

Response Type

rt

0..1

responseType element of data type responseTypeInfo (cf. clause 6.3.5.30 of TS-0004 [3])

Result Persistence

rp

0..1


Result Content

rcn

0..1


Delivery Aggregation

da

0..1

Allowed values are boolean-typed parameter. 'false', 'true', '0' and '1'

createdBefore

crb

0..1

filterCriteria condition

createdAfter

cra

0..1

filterCriteria condition

modifiedSince

ms

0..1

filterCriteria condition

unmodifiedSince

us

0..1

filterCriteria condition

stateTagSmaller

sts

0..1

filterCriteria condition

stateTagBigger

stb

0..1

filterCriteria condition

expireBefore

exb

0..1

filterCriteria condition

expireAfter

exa

0..1

filterCriteria condition

labels

lbl

0..n

filterCriteria condition

resourceType

ty

0..n

filterCriteria condition

sizeAbove

sza

0..1

filterCriteria condition

sizeBelow

szb

0..1

filterCriteria condition

contentType

cty

0..n

filterCriteria condition

limit

lim

0..1

filterCriteria condition

attribute

atr

0..n

filterCriteria condition

filterUsage

fu

0..1

filterCriteria condition

semanticsFilter

smf

0..n

filterCriteria condition, shall use "percent-encoding" [9] where required, see example 3)

filterOperation

fo

0..1

filterCriteria condition

contentFilterSyntax

cfs

0..1

filterCriteria condition

contentFilterQuery

cfq

0..1

filterCriteria condition

level

lvl

0..1

filterCriteria condition

offset

ofst

0..1

filterCriteria condition

numberOfInstances

noi

0..1

filterCriteria condition

geometryType

gmty

0..1

filterCriteria condition

geometry

geom

0..1

filterCriteria condition

geoSpatialFunction

gsf

0..1

filterCriteria condition

Discovery Result Type

drt

0..1


Role IDs

rids

0..n


Token IDs

tids

0..n


LocalTokenIDs

ltids

0..n


Token Request Indicator

tqi

0..1

Allowed values are boolean-typed parameter. 'false', 'true', '0' and '1'

Authorization Signature Indicator

asi

0..1

Allowed values are boolean-typed parameter. 'false', 'true', '0' and '1'

Authorization Relationship Indicator

auri

0..1

Allowed values are boolean-typed parameter. 'false', 'true', '0' and '1'

Semantic Query Indicator

sqi

0..1

Allowed values are boolean-typed parameter. 'false', 'true', '0' and '1'

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"?>
<m2m:rqp xmlns:m2m="http://www.onem2m.org/xml/protocols">
    <op>1</op>
    <to>//example.net/myCSE/-/Cont1</to>
    <fr>/myCSE/C2345</fr>
    <rqi>0002bf63</rqi>
    <ty>4</ty>
    <pc>
        <atrl>ri lbl rr </atrl>
    </pc>
</m2m:rqp>

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

  • Case 2 Primitive Example:

    <?xml version="1.0" encoding="UTF-8"?>
<m2m:rqp xmlns:m2m="http://www.onem2m.org/xml/protocols">
    <op>2</op>
    <to>//example.net/myCSE/-/Cont1#rr</to>
    <fr>/myCSE/C2345</fr>
    <rqi>0002bf63</rqi>
    <ty>4</ty>
</m2m:rqp>

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