Oma Ts Rest Netapi Common

Common definitions for RESTful Network APIs
Candidate Version 1.0 – 17 Apr 2012
Open Mobile Alliance

OMA-TS-REST_NetAPI_Common-V1_0-20120417-C
 2012 Open Mobile Alliance Ltd. All Rights Reserved.

Used with the permission of the Open Mobile Alliance Ltd. under the terms as stated in this document. [OMA-Template-Spec-20110101-I]
OMA-TS-REST_NetAPI_Common-V1_0-20120417-C Page 2 (45)
Use of this document is subject to all of the terms and conditions of the Use Agreement located at
http://www.openmobilealliance.org/UseAgreement.html.
Unless this document is clearly designated as an approved specification, this document is a work in process, is not an
approved Open Mobile Alliance™ specification, and is subject to revision or removal without notice.
You may use this document or any part of the document for internal or educational purposes only, provided you do not
modify, edit or take out of context the information in this document in any manner. Information contained in this document
may be used, at your sole risk, for any purposes. You may not use this document in any other manner without the prior
written permission of the Open Mobile Alliance. The Open Mobile Alliance authorizes you to copy this document, provided
that you retain all copyright and other proprietary notices contained in the original materials on any copies of the materials
and that you comply strictly with these terms. This copyright permission does not constitute an endorsement of the products
or services. The Open Mobile Alliance assumes no responsibility for errors or omissions in this document.
Each Open Mobile Alliance member has agreed to use reasonable endeavors to inform the Open Mobile Alliance in a timely
manner of Essential IPR as it becomes aware that the Essential IPR is related to the prepared or published specification.
However, the members do not have an obligation to conduct IPR searches. The declared Essential IPR is publicly available
to members and non-members of the Open Mobile Alliance and may be found on the “OMA IPR Declarations” list at
http://www.openmobilealliance.org/ipr.html. The Open Mobile Alliance has not conducted an independent IPR review of
this document and the information contained herein, and makes no representations or warranties regarding third party IPR,
including without limitation patents, copyrights or trade secret rights. This document may contain inventions for which you
must obtain licenses from third parties before making, using or selling the inventions. Defined terms above are set forth in
the schedule to the Open Mobile Alliance Application Form.
NO REPRESENTATIONS OR WARRANTIES (WHETHER EXPRESS OR IMPLIED) ARE MADE BY THE OPEN
MOBILE ALLIANCE OR ANY OPEN MOBILE ALLIANCE MEMBER OR ITS AFFILIATES REGARDING ANY OF
THE IPR’S REPRESENTED ON THE “OMA IPR DECLARATIONS” LIST, INCLUDING, BUT NOT LIMITED TO THE
ACCURACY, COMPLETENESS, VALIDITY OR RELEVANCE OF THE INFORMATION OR WHETHER OR NOT
SUCH RIGHTS ARE ESSENTIAL OR NON-ESSENTIAL.
THE OPEN MOBILE ALLIANCE IS NOT LIABLE FOR AND HEREBY DISCLAIMS ANY DIRECT, INDIRECT,
PUNITIVE, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES ARISING OUT OF OR IN
CONNECTION WITH THE USE OF DOCUMENTS AND THE INFORMATION CONTAINED IN THE DOCUMENTS.
© 2012 Open Mobile Alliance Ltd. All Rights Reserved.
Used with the permission of the Open Mobile Alliance Ltd. under the terms set forth above.

Contents
1. SCOPE ................................................................................................................................................................................ 5
2. REFERENCES................................................................................................................................................................... 6
2.1 NORMATIVE REFERENCES .......................................................................................................................................... 6
2.2 INFORMATIVE REFERENCES ....................................................................................................................................... 7
3. TERMINOLOGY AND CONVENTIONS ...................................................................................................................... 8
3.1 CONVENTIONS ............................................................................................................................................................. 8
3.2 DEFINITIONS ................................................................................................................................................................ 8
3.3 ABBREVIATIONS .......................................................................................................................................................... 8
4. INTRODUCTION ........................................................................................................................................................... 10
4.1 VERSION 1.0 .............................................................................................................................................................. 10
5. COMMON SPECIFICATIONS FOR RESTFUL NETWORK APIS ........................................................................ 11
5.1 USE OF REST GUIDELINES ....................................................................................................................................... 11
5.2 UNSUPPORTED FORMATS .......................................................................................................................................... 11
5.3 AUTHORING STYLE ................................................................................................................................................... 11
5.3.1 Names ................................................................................................................................................................ 11
5.3.2 Case usage for names ......................................................................................................................................... 11
5.4 CONTENT TYPE NEGOTIATION .................................................................................................................................. 11
5.5 RESOURCE CREATION ............................................................................................................................................... 12
5.5.1 General procedure of resource creation ............................................................................................................. 12
5.5.2 Error recovery during resource creation............................................................................................................. 12
5.6 JSON ENCODING IN HTTP REQUESTS/RESPONSES ................................................................................................ 13
5.6.1 Serialization rules: general conversion .............................................................................................................. 13
5.6.2 Serialization rules: structure-aware conversion ................................................................................................. 15
5.6.3 Rules for JSON-creating and JSON-consuming applications ............................................................................ 17
5.7 ENCODING AND SERIALIZATION DETAILS FOR MIME FORMAT............................................................................. 17
5.8 RESOURCE URL CONSIDERATIONS .......................................................................................................................... 18
5.8.1 Resource URL structure ..................................................................................................................................... 18
5.8.2 API version signaling ......................................................................................................................................... 19
5.8.3 Handling of unsupported versions ..................................................................................................................... 19
5.9 BACKWARD COMPATIBILITY .................................................................................................................................... 20
6. DATA ITEMS .................................................................................................................................................................. 22
6.1 ADDRESS DATA ITEMS ............................................................................................................................................... 22
6.2 COMMON DATA TYPES .............................................................................................................................................. 22
6.2.1 Structures ........................................................................................................................................................... 22
6.2.2 Enumerations ..................................................................................................................................................... 24
6.3 CHARGING ................................................................................................................................................................. 25
6.3.1 Charging data type ............................................................................................................................................. 25
7. ERROR HANDLING ...................................................................................................................................................... 27
7.1 HTTP RESPONSE CODES .......................................................................................................................................... 27
7.2 HANDLING OF NOT ALLOWED HTTP METHODS ...................................................................................................... 28
7.3 HTTP RESPONSE CODES IN RESPONSE TO NOTIFICATIONS ................................................................................... 28
APPENDIX A. CHANGE HISTORY (INFORMATIVE) .............................................................................................. 29
A.1 APPROVED VERSION HISTORY ................................................................................................................................. 29
A.2 DRAFT/CANDIDATE VERSION 1.0 HISTORY ............................................................................................................. 29
APPENDIX B. SHARED DEFINITIONS FOR EXCEPTION HANDLING IN RESTFUL NETWORK APIS
BASED ON PARLAY X (NORMATIVE) ............................................................................................ 31
B.1 COMMON DATA TYPES FOR EXCEPTION HANDLING ................................................................................................. 31
B.1.1 Type: RequestError ............................................................................................................................................ 31
B.1.2 Type: ServiceException ..................................................................................................................................... 31
B.1.3 Type: PolicyException ....................................................................................................................................... 31
B.1.4 Type: ServiceError ............................................................................................................................................. 32
B.2 HANDLING OF SERVICE AND POLICY EXCEPTIONS .................................................................................................. 32

B.2.1 Service exception ............................................................................................................................................... 32
B.2.2 Policy exception ................................................................................................................................................. 33
APPENDIX C. COMMON EXCEPTION DEFINITIONS (NORMATIVE) ............................................................... 34
C.1 SERVICE EXCEPTIONS ............................................................................................................................................... 34
C.2 COMMON POLICY EXCEPTIONS................................................................................................................................ 36
APPENDIX D. DEPLOYMENT CONSIDERATIONS (INFORMATIVE) ................................................................. 41
D.1 RESTFUL CLIENT APPLICATION EXECUTING IN A SERVER EXECUTION ENVIRONMENT ........................................ 42
D.2 RESTFUL CLIENT APPLICATION EXECUTING IN A MOBILE DEVICE EXECUTION ENVIRONMENT ........................... 42
D.3 RESTFUL CLIENT APPLICATION EXECUTING IN A FIXED DEVICE EXECUTION ENVIRONMENT .............................. 43
APPENDIX E. AUTHORIZATION ASPECTS (NORMATIVE) ................................................................................. 44
E.1 USE OF AUTHO4API ................................................................................................................................................. 44
E.1.1 Endpoint URLs .................................................................................................................................................. 44
E.1.2 Scope values ...................................................................................................................................................... 44
Figures
Figure 1 RESTful Network API accessed from a server execution environment (e.g. 3rd party Service Provider
application) ....................................................................................................................................................................... 42
Figure 2 RESTful Network API accessed from a mobile device execution environment .................................................. 43
Figure 3 RESTful Network API accessed from a fixed device execution environment ..................................................... 43
Tables
Table 1: ChargingInformation Structure .............................................................................................................................. 23
Table 2: CallbackReference Structure................................................................................................................................... 23
Table 3: ResourceReference Structure .................................................................................................................................. 23
Table 4: Link Structure ........................................................................................................................................................... 24
Table 5: VersionedResource structure................................................................................................................................... 24
Table 6: VersionedResourceList structure ............................................................................................................................ 24
Table 7: NotificationFormat Values ....................................................................................................................................... 25
Table 8: RetrievalStatus .......................................................................................................................................................... 25
Table 9: RequestError............................................................................................................................................................. 31
Table 10: ServiceException ..................................................................................................................................................... 31
Table 11: PolicyException ....................................................................................................................................................... 31
Table 12: ServiceError ............................................................................................................................................................ 32

1. Scope
The scope of this specification is to provide common definitions and specification material for RESTful Network APIs in
OMA.

2. References
2.1 Normative References
[Autho4API_10] “Authorization Framework for Network APIs”, Open Mobile Alliance™, OMA-ER-Autho4API-
V1_0, URL: http://www.openmobilealliance.org/
[HTML FORMS] “HTML Forms”, W3C Recommendation, URL:http://www.w3.org/TR/html401/interact/forms.html
[IETF_ACR_draft] “The acr URI for anonymous users”, S.Jakobsson, K.Smith, July 2011, URL:
http://tools.ietf.org/html/draft-uri-acr-extension-03
[ISO4217] “ISO 4217 currency names and code elements”, URL: http://www.iso.org/
[OMNA_Autho4API] Open Mobile Naming Authority “Autho4API Scope Values Registry”, Open Mobile Alliance™,
URL: http://www.openmobilealliance.org/tech/omna
NOTE: The hyperlink above will point directly to the OMNA registry page once available.
[ParlayX_Common] “Open Service Access (OSA); Parlay X web services; Part 1: Common”, 3GPP TS 29.199-01, Release
8, Third Generation Partnership Project, URL: http://www.3gpp.org/ftp/Specs/html-info/29-series.htm
[PSA] “Reference Release Package for Parlay Service Access”, Open Mobile Alliance™, OMA-ERP-PSA-
V1_0, URL: http://www.openmobilealliance.org/
[REST_NetAPI_CallNotif] “RESTful Network API for CallNotification”, Open Mobile Alliance™, OMA-TS-
REST_NetAPI_CallNotification-V1_0, URL: http://www.openmobilealliance.org/
[REST_NetAPI_Notif_Cha “RESTful Network API for Notification Channel”, Open Mobile Alliance™, OMA-TS-
nnel] REST_NetAPI_NotificationChannel-V1_0, URL: http://www.openmobilealliance.org/
[RFC2119] “Key words for use in RFCs to Indicate Requirement Levels”, S. Bradner, March 1997, URL:
http://www.ietf.org/rfc/rfc2119.txt
[RFC2387] “The MIME Multipart/Related Content-type”, E. Levinson, August 1998, URL:
[RFC2388] “Returning Values from Forms: multipart/form-data”, L. Masinter, August, 1998,
URL:http://www.ietf.org/rfc/rfc2388.txt
[RFC2616] “Hypertext Transfer Protocol -- HTTP/1.1”, R. Fielding et. al, June 1999, URL:
[RFC3261] “SIP: Session Initiation Protocol”, J. Rosenberg, et. Al, June 2002, URL:
[RFC3986] “Uniform Resource Identifier (URI): Generic Syntax”, T. Berners-Lee, R. Fielding, L. Masinter,
January 2005, URL: http://www.ietf.org/rfc/rfc3986.txt
[RFC3966] “The tel URI for Telephone Numbers”, H. Schulzrinne, December 2004, URL:
[RFC4122] “A Universally Unique IDentifier (UUID) URN Namespace”, P. Leach, M. Mealling, R. Salz, July
2005, URL: http://www.ietf.org/rfc/rfc4122.txt
[RFC4627] “The application/json Media Type for JavaScript Object Notation (JSON)”, D. Crockford, July 2006,
URL: http://www.ietf.org/rfc/rfc4627.txt
[W3C-XML11] W3C XML 1.1 Specification, URL: http://www.w3.org/TR/xml11/
[W3C_URLENC] HTML 4.01 Specification, Section 17.13.4 Form content types, The World Wide Web Consortium,
URL: http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1
[XMLSchema1] W3C Recommendation, XML Schema Part 1: Structures Second Edition, URL:
http://www.w3.org/TR/xmlschema-1/
[XMLSchema2] W3C Recommendation, XML Schema Part 2: Datatypes Second Edition, URL:
http://www.w3.org/TR/xmlschema-2/

2.2 Informative References
[OMADICT] “Dictionary for OMA Specifications”, Version 2.8, Open Mobile Alliance™,
OMA-ORG-Dictionary-V2_8, URL: http://www.openmobilealliance.org/
[OMA_PUSH] "Push Access Protocol Specification". Open Mobile Alliance™. OMA-WAP-TS-PAP-V2_3
URL:http://www.openmobilealliance.org/
[OMA_REST_Common] “Common definitions and specifications for OMA REST interfaces”, Open Mobile Alliance™, OMA-
TS-REST_Common-V1_0, URL: http://www.openmobilealliance.org/
[ParlayREST_Common] “RESTful bindings for Parlay X Web Services - Common”, Open Mobile Alliance™, OMA-TS-
ParlayREST_Common-V1_1, URL: http://www.openmobilealliance.org/
[REST_NetAPI_WP] “Guidelines for RESTful Network APIs”, Open Mobile Alliance™,

OMA-WP-Guidelines_for_RESTful_Network_APIs, URL:http://www.openmobilealliance.org/
[XML2JSON] Open source “UNICA” XML to JSON conversion tool URL: http://forge.morfeo-
project.org/projects/unicaxml2json/

3. Terminology and Conventions

3.1 Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
“RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
All sections and appendixes, except “Scope” and “Introduction”, are normative, unless they are explicitly indicated to be
informative.
3.2 Definitions
For the purpose of this TS, all definitions from the OMA Dictionary apply [OMADICT].
Client-side
An HTTP URL exposed by a client, on which it is capable of receiving notifications and that can be used by the
Notification
client when subscribing to notifications.
URL
Long Polling A variation of the traditional polling technique, where the server does not reply to a request unless a particular event,
status or timeout has occurred. Once the server has sent a response, it closes the connection, and typically the client
immediately sends a new request. This allows the emulation of an information push from a server to a client.
Notification A channel created on the request of the client and used to deliver notifications from a server to a client. The channel
Channel is represented as a resource and provides means for the server to post notifications and for the client to receive them
via specified delivery mechanisms.
For example in the case of Long Polling the channel resource is defined by a pair of URLs. One of the URLs is used
by the client as a callback URL when subscribing for notifications. The other URL is used by the client to retrieve
notifications from the Notification Server.
Notification
A server that is capable of creating and maintaining Notification Channels.
Server
Server-side
An HTTP URL exposed by a Notification Server, that identifies a Notification Channel and that can be used by a
Notification
client when subscribing to notifications.
URL
3.3 Abbreviations
ACR Anonymous Customer Reference

AGPL Affero General Public License
API Application Programming Interface
DNS Domain Name Server
HTTP Hypertext Transfer Protocol
ID Identifier
IP Internet Protocol
JSON JavaScript Object Notation
OMA Open Mobile Alliance
PLMN Public Land Mobile Network
REST REpresentational State Transfer
URI Uniform Resource Identifier

URL Uniform Resource Locator

UUID Universal Unique Identifier
XML Extensible Markup Language
XSD XML Schema Definition

4. Introduction
To ensure consistency for developers using the various RESTful Network APIs specified in OMA, this “Common” technical
specification aims to contain all items that are common across all HTTP protocol bindings using REST architectural style for
the various individual interface definitions, such as naming conventions, content type negotiation, representation formats and
serialization, and fault definitions. It also provides a repository for common data types.
4.1 Version 1.0

This version of the Common Definitions and Specifications for RESTful Network APIs is a republication of the ParlayREST
Common V 1.1 [ParlayREST_Common] and OMA REST Common V 1.0 [OMA_REST_Common] specifications from the
ParlayREST 2.0 release as part of the suite of OMA RESTful Network APIs. The content of these two specifications has
been merged and restructured to fit that suite, and to separate general aspects from those aspects that are related to a Parlay X
baseline [PSA]. Further, only bug fixes, but no functional changes have been applied.
Version 1.0 of the Common Definitions and Specifications for RESTful Network APIs contains naming conventions, content
type negotiation, resource creation, representation formats and serialization, fault definitions and common data types for
RESTful Network APIs. It also includes an Annex that provides specifications which are shared by those RESTful Network
APIs which are based on Parlay X baselines .

5. Common Specifications for RESTful Network APIs

5.1 Use of REST Guidelines
REpresentational State Transfer (REST) is an architectural style for defining distributed systems. Entities in these systems
communicate using the interfaces they expose. Guidelines for defining RESTful Network APIs in OMA, including general
key principles, have been collected in [REST_NetAPI_WP].
5.2 Unsupported Formats

Servers must return a 406 Not Acceptable error if a message body format (e.g. XML or JSON) requested by the application is
not supported [RFC2616].
5.3 Authoring Style

5.3.1 Names
Names will be meaningful, and not abbreviated in a way that makes the name hard to understand for users of the REST
interfaces that are not literate in computer programming. This does not preclude the use of commonly understood acronyms
within names (e.g. ID) or commonly used abbreviations (e.g. max). However, the resulting name must still be meaningful.
5.3.2 Case usage for names

Two general cases are provided for, both using mixed case names; one with a leading capital letter, the other with a leading
lowercase letter.
Names will start with a letter and be mixed case, with the leading letter of each but the first word capitalized. The
conventions for the leading letter of the first differ depending on the context, as given below. Words will not be separated by
white space, underscore, hyphen or other non-letter character.
The following names will have a leading uppercase letter – Type names and value names in an enumeration.
The following names will have a leading lowercase letter – all other names.
For names consisting of concatenated words, all subsequent words start with a capital, for example, “concatenatedWord” or
“BothCapitals”. If a lowercase name starts with an abbreviation, all characters of the abbreviation are de-capitalized, e.g.
“smsService”.
Path components of resource names are mixed case, with the leading letter lowercase. The leading path component which
identifies the RESTful Network API (e.g. thirdpartycall) is all lowercase, and is aligned with the namespace name of the
related XML schema.
5.4 Content type negotiation

The Content type of a response used SHALL be established using the following methodology:
As a general rule, content type used in response message body must match content type used in request body. At least XML
and JSON content types MUST be supported.
Support for other content types will be specified on a case-by-case basis (e.g. simple name-value pair parameters may be
accepted in the URL when using GET and application/x-www-form-urlencoded [W3C_URLENC] may be supported for the
request message body when using POST or PUT).
Content type of the request message body SHALL always be determined by Content-Type header of the HTTP message.
Content type of the response body SHALL be determined using the following methodology. When invoking the RESTful
Network API, the requesting application SHOULD include the ‘Accept’ request header, and provide the primary content type
choice, and OPTIONALLY any supported substitute content types, in this request Accept header.
a. If the server does not support the content type choice listed as priority in the Accept header, it SHALL attempt
to return the next preferred choice if one was provided.
b. If the requesting application does not provide an Accept header or any other indication of desired content type
of the response (see further below), and the request message body content type is XML or JSON, then the server

SHALL provide a response message body with the content type matching that of the request message body. For
example, a request with an XML body and no Accept header will trigger an XML response.
c. If the requesting application requires the response message body to be of a different content type than the one
determined by the request message body and the Accept header negotiations, it MUST request that content type
by inserting in the URL path the query parameter “?resFormat={content type}”, where content type SHALL be
either XML or JSON. This option overrides the Accept header provided by the application, if present, and the
response format SHALL be determined solely by the “resFormat” parameter. Note that this allows an
application that does not have sufficient control over the HTTP headers to enforce a response format regardless
of the value of the Accept header.
d. If the server cannot return any of the content types based on the negotiation steps described, it SHALL return a
406 response code as per [RFC2616].
e. The default format for notification payloads SHALL be XML, unless the client has specified
notificationFormat=”JSON” in the subscription.
f. Content type SHALL accompany HTTP response codes 200, 201, 400, 409 in the conditions dictated by the
above specified methodology, and MAY be omitted in other cases.
5.5 Resource creation

5.5.1 General procedure of resource creation
Typically, a resource is created either following a POST request (to create a child of an existing resource that is addressed by
the request), or following a PUT request (to create a new resource as addressed by the request).
If a resource has been created on the server, the server SHALL return an HTTP response with a "201 Created" header and the
Location header containing the location of the created resource, and SHALL include in the response body either a
resourceReference element, or a representation of the created resource. Note that this allows the server to control the traffic.
Further note that REST resource representations are designed in such a way that they can include a self reference. (i.e.
resourceURL element.). A self reference is always present in any data structure that is a representation of a resource created
by POST, and can be included as necessary in other cases. Since a self reference can be defined as a mandatory or optional
element to accommodate different situations, the normative aspects on the client and on the server in each optional usage
instance in the specification are clarified as follows: the resourceURL SHALL NOT be included in POST requests by the
client, but MUST be included in POST requests representing notifications by the server to the client, when a complete
representation of the resource is embedded in the notification. The resourceURL also MUST be included in responses to any
HTTP method that returns an entity body, and in PUT requests.
Generally resources are used to access entire data structure and those resources are regarded as heavy-weight resources. To
access a part of the data structure or an individual elements in the data structure, another type of resources called light-weight
resources are used. Compared to heavy-weight resources, light weight resources are created following PUT request only (see
[REST_NetAPI_WP] for more details about light-weight resources).
Elements in data structures with a key properties (keys) are normally not accessable by using light-weight resources, however
when accessing other elements using light-weight resources they may appear in both the light-weight resource URL and in
the body of the request. In case the server receives PUT request with keys, it SHALL ensure that the key value(s) specified in
the URL match those value(s) specified in the body of the request. If not, the server SHALL respond with “409 Conflict”
indicating key value(s) conflict.
5.5.2 Error recovery during resource creation

The following mechanism allows recovery from communication failures that can occur during resource creation using POST.
The client MAY (and in some cases SHOULD) include in the parameter set of the resource creation request the
"clientCorrelator" field which uniquely maps to the resource to be created.

Note that this allows the client to retry a resource-creating request for which it did not receive an answer due to
communication failure, and prevents the duplicate creation of resources on the server side in case of such retry. Note further
that depending on the deployment (e.g. Network Address Translation, Proxies), the server might or might not be able to
distinguish between different clients.
It is therefore RECOMMENDED that the client generates the value of the “clientCorrelator” in such a way that collisions (i.e.
two unrelated requests use the same “clientCorrelator” value) are impossible or at least highly improbable. The way this is
achieved is out of scope of this specification, however, it is pointed out that for example UUID [RFC4122] provides a way to
implement such a scheme.
In case the server receives a “clientCorrelator” value in a resource-creating POST request, it SHALL do the following:
 in case the request contains a “clientCorrelator” value that has not been used yet to create a resource, the server
SHALL create the resource and respond with "201 Created", as above.
 in case the request contains a “clientCorrelator” value that has already been used to create a resource, the server
responds as follows:
 in case this is a valid repeated attempt by the same client to create the same resource, the server SHALL respond
with "200 OK", and SHALL return a representation of the resource.
 otherwise, it SHALL respond with "409 Conflict", in this case indicating a clientCorrelator conflict, and SHOULD
include a payload with a “requestError” structure carrying a “SVC0005 Duplicate correlator” ServiceException. In
such case, the client can retry the request using a new “clientCorrelator” value.
5.6 JSON encoding in HTTP Requests/Responses

5.6.1 Serialization rules: general conversion
Specifications of RESTful Network APIs MAY include XML schema files defining the data structures used by that API, for
its direct usage in XML format. The following are general rules for mapping between XML and JSON data formats:
a. XML elements that appear at the same XML hierarchical level (i.e. either root elements or within the same
XML parent element), are mapped to a set of name:value pairs within a JSON object, as follows:
(i) Each XML element appearing only once at the same hierarchical level (“single element”) is
mapped to an individual name:value pair. The name is formed according to bullet b, while the
value is formed according to bullet c.
(ii) XML elements appearing more than once at the same hierarchical level (“element list”) are
mapped to only one, individual name:value pair. The name is formed according to bullet b, while
the value is a JSON array containing one value per each occurrence of the XML element. The
name is formed according to bullet b whilst values are formed according to bullet c.
(iii) Name and Value of JSON objects will go between “”. Additionally, any JSON representation of an
element of complex type will go between {}, according to [RFC4627].
b. The name of the name:value pair is the name of the XML elements (i.e. XML_element_name:value)
c. The value is formed as follows:
(i) when the XML element has neither attributes nor child XML elements, the value is equal to the
value of the XML element. In case the element is nill (i.e it has no value), it will be indicated as
having a “null” value within JSON.
(ii) when the XML element has child elements and/or attributes, the value is a JSON object
containing the following name:value pairs:

- one name:value pair per each attribute, where name is the name of the attribute and value is the
value of the attribute.
- one name:value pair associated to the text value (simple type content) of the XML element,
where name is the string “$t” and value is the value of the XML element.
- name:value pairs associated to XML child elements. These name:value pairs are formed in
accordance with bullet a.
Within JSON, there is no need to reflect:
 the first <?xml version="1.0" encoding="UTF-8" ?> tag
 declaration of namespaces or schemaLocations
In order to generate unambiguous JSON from XML instances, based on the rules defined above, the following limitations
need to be imposed on the XML data structures:
 it is not allowed that two different elements from different namespaces have the same name, in case they appear
at the same level
 within an XML parent element, no attribute is allowed to have the same name as a child element of this parent
element.
Note: These general rules have been used to generate the JSON examples from the XML examples in the Technical
Specifications of the RESTful Network APIs.
5.6.1.1 Utility which implements the general conversion rules (Informative)
The general conversion rules are implemented with UNICA XML2JSON utility, an open source tool, distributed, under an
AGPL license, within the open source community MORFEO [XML2JSON].
5.6.1.2 Example (Informative)
The following is an example illustrating the guidelines:
Input XML content:
<Animals>
<dog>
<name attr="1234">Rufus</name>
<Breed>labrador</Breed>
</dog>
<dog>
<name>Marty</name>
<Breed>whippet</Breed>
<a/>
</dog>
<dog/>
<cat name="Matilda"/>
<a/>
</Animals>
Transformed JSON:

{"Animals": {
"a": null,
"cat": {"name": "Matilda"},
"“dog": [
{
"Breed": "labrador",
"name": {
"$t": "Rufus",
"attr": "1234"
}
},
{
"Breed": "whippet",
"a": null,
"name": "Marty"
},
null
]
}}
5.6.2 Serialization rules: structure-aware conversion

The general approach as defined above relies only on the information in the XML data instance.
The structure-aware approach defined in this section considers information in a data instance (e.g. XML) plus further
information about the data structure definition (such as the allowed number of element occurrences), as documented in the
RESTful Network API specifications and XML Schemas.
This structure-aware approach allows having always the same JSON structure to convey lists of elements.
In this conversion approach, the rules above apply, except for the following modification to the conditions in
a (i) and a (ii):If an element is allowed to appear more than once at the same hierarchical level, it SHALL be
treated according to a (ii) as element list, otherwise it SHALL be treated according to a (i) as single element.
5.6.2.1 Example (Informative)
The following example illustrates the structure-aware serialization.
In the example, the data instance is represented as XML document:
<Animals>
<dog>
<name attr="1234">Rufus</name>
<Breed>labrador</Breed>
</dog>
<dog>
<name>Marty</name>
<Breed>whippet</Breed>
<a/>
</dog>
<dog/>
<cat name="Matilda"/>
<a/>

</Animals>
The information about the data structure is represented as XML schema in this example. Note that the maximum cardinality
of the elements is the only piece of information that is used here.
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="Animals">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="dog" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="attr" type="xsd:string"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="Breed" type="xsd:string" minOccurs="0"/>
<xsd:element name="a" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="cat" maxOccurs="unbounded">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="a"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Transformed JSON:
{"Animals": {
"dog": [
{

"name": {
"$t": "Rufus",
"attr": "1234"
}
"Breed": "labrador",
},
{
"name": "Marty"
"Breed": "whippet",
"a": null,
},
null
]
"cat": [{"name": "Matilda"}],
"a": null,
}}
5.6.3 Rules for JSON-creating and JSON-consuming applications

A JSON-creating application SHALL use either the structure-aware or the general approach, but not both.
Applications that consume a JSON representation SHALL accept the following two different JSON representations for an
array that contains one element:
1. a pair of name and value (e.g. “name”: “one”)
2. a pair of name and array of one value (e.g. “name”: [“one”])

Note: In JSON, according to [RFC4627], the order of objects is not significant, whilst the order of values within an array is.
5.7 Encoding and Serialization Details for MIME format

A MIME multipart message often consists of several parts:
 The root structure, which is a data structure defined in the RESTful Network API specification, expressed in the
different possible formats (such as XML or JSON). This part conveys the resource parameters.
 The multimedia contents or attachments as MIME body parts, within the HTTP request or response. They include all
contents, both plain text as well as other content types (images, videos, etc).
To represent such MIME multipart messages, there are different options available, namely multipart/related [RFC2387], and
multipart/form-data [RFC2388]. The selection of the multipart format to use in a particular API needs to consider multiple
factors, such as the conventions in the domain in which the API is defined, how tightly the API is to be coupled to the
underlying systems, and how easy the format is to use in the Web community and in browser environments.
In OMA RESTful Network APIs, for simplicity purposes and better suitability to the internet developer community and
browsers, multipart/form-data [RFC2388] and [HTML FORMS] can be used instead of multipart/related.
To represent the differente categories of message parts in a multipart/form-data message, the following is defined:
1. Root fields as described above SHALL be included as a single form field with a MIME body with:
Content-Disposition: form-data; name=”root-fields”

Content-Type: <Corresponding Content type>

Allowed content types for the root fields are:
 application/xml
 application/json
 application/x-www-form-urlencoded
2. Multimedia contents (text, images, etc.) SHALL be included using one of the following two options:
a. When the message contains only one content item: By including a MIME body with:
Content-Disposition: form-data; name=“attachments”, filename=“<Name of the message content>”
Content-Type: <Corresponding Content-Type>
b. When the message contains more than one content item: By including a form-field with a MIME body with:
Content-Disposition: form-data; name=“attachments”
Content-Type: multipart/mixed
Then, every one of the possible message contents SHALL be included as subparts, with:
Content-Disposition: attachment; filename=“<Name of the message content>” Content-Type:
<Corresponding Content-Type>
3. For every MIME body part and subparts, it is possible to include other parameters (Content-Description, Content-
Transfer-Encoding, Content-ID), etc.
5.8 Resource URL considerations

5.8.1 Resource URL structure
Each resource URL consists of fixed and variable parts.
For fixed parts, the exact string value is defined by this specification. Implementations SHALL use the exact string of fixed
parts.
For variable parts, rules how to build the string value are defined by this specification. Implementations SHALL follow these
rules. The variable parts are referred to as “Resource URL variables” in the individual OMA RESTful Network API
specifications. Resource URL variables are denoted by a name in curly brackets, such as {apiVersion}.
5.8.1.1 Use of ‘acr:Authorization’ as a resource URL variable
In the case where a resource URL includes a resource URL variable that identifies a user (e.g. {endUserId},
{senderAddress}, etc), the value of this variable MAY be in the form of an ‘acr’ URI [IETF_ACR_draft].
The use of ‘acr:Authorization’ is a special case that SHALL be suported. The reserved keyword ‘Authorization’ MUST not
be assigned as an ACR to any particular user.
When detecting ‘acr:Authorization’ in the resource URL path the server SHALL:
1. validate the authorization token passed with the request. The server SHALL then use the authorization token to generate
a unique identifier mapped to the real user identity, and SHALL replace ‘acr:Authorization’ with that generated unique
identifier in the resource URL path, as well as in any applicable elements in the response body (e.g. ‘resourceURL,
‘link’, etc).
2. return an HTTP response code “400 Bad Request” if the authorization token is not present in the request or “401
Unauthorized” if the authorization token is invalid.

For more details on authorization see Appendix E of this specification and [Autho4API_10].
For any specific impact regarding the use of ‘acr:Authorization’ on a particular OMA RESTful Network API, see the
Technical Specification for that particular OMA RESTful Network API.
5.8.2 API version signaling

Each resource URL contains a variable "apiVersion" which signals the version of the API that is used. The value of this
variable SHALL be set to "v1" in the initial version of a particular API. In subsequent revisions of the aforementioned API
the digit SHALL be incremented by “1” (e.g. increment from “v1” to “v2”).
In each HTTP request sent by the application, the “apiVersion” variable MUST be included in the Request-URI field (which
is defined by [RFC2616]). The following applies to the server answering such a request:
 If the server supports the version signaled by the application, it MUST use the same version in the response, as
follows: In each HTTP response sent by the server to answer such a request, the “apiVersion” variable MUST be
present in the “resourceURL” element(s) in the body of the response. Additionally, if the response contains a
“Location” HTTP header (e.g. in case of responses to a resource creation request), the “apiVersion” variable MUST
also be present in the URL signaled in that header.
 Otherwise, the server MUST respond as defined in section 5.8.3.
In an HTTP request sent by the server towards the application (i.e. a notification), the server MUST use in the Request-URI
field a resource URL with the same API version as in the subscription which has triggered the notification.
Note that the change in the API version can imply a change of the actual data structures used, and functionality offered.
5.8.3 Handling of unsupported versions

In case the server does not support the API version that the application has signaled in a request, but the server supports other
versions of the resource in question, the server MUST return a response that lists the available versions and related resource
URLs on which the client could repeat the request.
For that, the server MUST return a “300 Multiple Choices” response, with a “versionedResourceList” root element as defined
in section 6.2.1.7. In case there is only one version supported by the server, the HTTP header “Location” MUST be populated
with the according resource URL. In case there are multiple versions supported by the server, the server MAY populate the
“Location” header with the choice deemed most appropriate given the version that was requested. Usually this is the highest
version supported by the server which is lower than the requested one.
5.8.3.1 Example 1: Signalling supported versions in case an unsupported version

was requested (XML format) (Informative)
5.8.3.1.1 Request
GET /exampleAPI/smsmessaging/v2/outbound/tel%3A%2B19585550151/requests HTTP/1.1

Accept: application/xml
Host: example.com
5.8.3.1.2 Response
HTTP/1.1 300 Multiple Choices

Content-Type: application/xml
Content-Length: nnnn
Location: http://example.com/exampleAPI/smsmessaging/v1/outbound/tel%3A%2B19585550151/requests

Date: Thu, 04 Jun 2009 02:51:59 GMT
<?xml version="1.0" encoding="UTF-8"?>

<common:versionedResourceList xmlns:common="urn:oma:xml:rest:netapi:common:1">
<resourceReference>
<apiVersion>v1</apiVersion>
<resourceURL>http://example.com/exampleAPI/smsmessaging/v1/outbound/tel%3A%2B19585550151/requests</resourceURL>
</resourceReference>
<resourceReference>
<apiVersion>v3</apiVersion>
<resourceURL>http://example.com/exampleAPI/smsmessaging/v3/outbound/tel%3A%2B19585550151/requests</resourceURL>
</resourceReference>
</common:versionedResourceList>
5.8.3.2 Example 2: Signalling supported versions in case an unsupported version

was requested (JSON format) (Informative)
5.8.3.2.1 Request
GET /exampleAPI/smsmessaging/v2/outbound/tel%3A%2B19585550151/requests HTTP/1.1

Accept: application/json
Host: example.com
5.8.3.2.2 Response
HTTP/1.1 300 Multiple Choices

Content-Type: application/json
Content-Length: nnnn
Location: http://example.com/exampleAPI/smsmessaging/v1/outbound/tel%3A%2B19585550151/requests
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"versionedResourceList": {"resourceReference": [
{
"apiVersion": "v1",
"resourceURL": "http://example.com/exampleAPI/smsmessaging/v1/outbound/tel%3A%2B19585550151/requests"
},
{
"apiVersion": "v3",
"resourceURL": "http://example.com/exampleAPI/smsmessaging/v3/outbound/tel%3A%2B19585550151/requests"
}
]}}
5.9 Backward compatibility

When processing an XML data structure that contains attributes and/or elements not known to a client/server conforming to a
certain version of the API, the result of processing that data structure SHALL be the same as the result of processing a data
structure where these attributes, or elements including their child elements and attributes, were not present.
When processing a JSON data structure that contains name-value-pairs where the name is not known to a client/server
conforming to a certain version of the API, the result of processing that data structure SHALL be the same as the result of
processing a data structure where these name-value pairs including their child name-value pairs were not present.

When processing an application/x-www-form-urlencoded [W3C_URLENC] data structure that contains name-value-pairs

where the name is not known to a client/server conforming to a certain version of the API, the result of processing that data
structure SHALL be the same as the result of processing a data structure where these name-value pairs were not present.
Note: backward compatibility processing of XML, JSON or application/x-www-form-urlencoded data structures, as
described above, can be achieved by ignoring the unknown attributes or elements and their child elements/attributes.

6. Data Items
6.1 Address data items
Addresses, unless the specification provides specific additional instruction, MUST conform to the address portion of the URI
definition provided in [RFC3966] for 'tel:' URIs, [RFC3261] for 'sip:' URIs, [IETF_ACR_draft] for 'acr' URIs or the
definition given below for shortcodes or aliased addresses. Optional additions to the address portion of these URI definitions
MUST NOT be considered part of the address accepted by the RESTful Network APIs, and an implementation MAY choose
to reject an address as invalid if it contains any content other than the address portion.
A tel: URI MUST be defined as a global number (e.g. tel:+19585550100). The use of characters other than digits and the
leading “+” sign SHOULD be avoided in order to ensure uniqueness of the resource URL. This applies regardless of whether
the user identifier appears in a URL variable or in a parameter in the body of an HTTP message.
When specified in the definition of a service operation, the URI may contain wildcard characters in accordance with the
appropriate specification (i.e. [RFC3966] or [RFC3261]).
Shortcodes are short telephone numbers, usually 4 to 6 digits in length reserved for telecom service providers' own
functionality. They shall be differentiated from national addresses by the use of a 'short' rather than 'tel' URI scheme. The
short code defined in the URI consists of a string of digits with no non-digit characters.
Support for aliases in addresses is provided by use of the URI defined in [RFC3986]. One can not assume that the resource
the alias references can be determined without using the URI to access the resource.
An alias is generally a relatively short character string that holds a scrambled address such that only the application identified
in the URI can expand it.
6.2 Common data types

This section defines data types which are shared among two or more RESTful Network APIs.
The namespace for the common data types is:
urn:oma:xml:rest:netapi:common:1
The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema
[XMLSchema1, XMLSchema2]. The use of the name 'xsd' is not semantically significant.
6.2.1 Structures
6.2.1.1 Type: ChargingInformation
For services that include charging as an inline message part, the charging information is provided in this data structure. See
section 6.3 for more information.

Element Type Optional Description

description xsd:string No An array of description text to be used for information and billing
[1..unbounded] text.
currency xsd:string Yes Currency identifier as defined in [ISO4217].
amount xsd:decimal Yes Amount to be charged/refunded/reserved.
The amount to be charged/refunded/reserved appears either
directly in the amount-field or as code in the code-field. If both
these two fields are missing or empty a service exception
(SVC0007) will be thrown.
code xsd:string Yes Charging code, referencing a contract under which the charge is
applied.
Table 1: ChargingInformation Structure
6.2.1.2 Type: CallbackReference

An application can use the CallbackReference data structure to subscribe to notifications.
If a parameter callbackData has been passed in a particular subscription, the server MUST copy it into each notification
which is related to that particular subscription.

notifyURL xsd:anyURI No Notify Callback URL
callbackData xsd:string Yes Data the application can register with the server when
subscribing to notifications, and that are passed back
unchanged in each of the related notifications. These
data can be used by the application in the processing of
the notification, e.g. for correlation purposes.
notificationFormat NotificationFormat Yes
Default: XML
Application can specify format of the resource
representation in notifications that are related to this
subscription. The choice is between {XML, JSON}
Table 2: CallbackReference Structure
Note: In case the application requires correlating notifications to the related subscription, it can either submit a different
notifyURL in each subscription, or use the optional callbackData parameter as a correlator.
6.2.1.3 Type: ResourceReference

resourceURL xsd:anyURI No The URL that addresses the resource. The resourceURL SHALL
NOT be included in POST requests by the client, but MUST be
included in POST requests representing notifications by the
server to the client, when a complete representation of the
resource is embedded in the notification. The resourceURL
MUST also be included in responses to any HTTP method that
returns an entity body, and in PUT requests.
Table 3: ResourceReference Structure
The resourceReference element of type ResourceReference is defined as a root element in the XSD.

6.2.1.4 Type: Link

Attribute Type Optional Description
rel xsd:string No Describes the relationship between the URI and the resource
href xsd:anyURI No URI
Table 4: Link Structure
An element of type Link can be provided by the server to point to other resources that are in relationship with the resource.
The rel attribute is a string. The possible values for the string are defined in each RESTful Network API. Rel and href are
realized as attributes in the XSD.
6.2.1.5 Type: LanguageString
String with an attribute that signals the language of the contained text.
This type is defined as a string of base type xsd:string with an OPTIONAL instance of the built-in XML attribute xml:lang
[W3C-XML11].
6.2.1.6 Type: VersionedResource

A resource with associated version string.
apiVersion xsd:string No The API version provided by the resource.
resourceURL xsd:anyURI No The URL that addresses the resource.
Table 5: VersionedResource structure
6.2.1.7 Type: VersionedResourceList

A list of resources with associated version string.
This data structure and associated root element is intended to signal a list of supported resource versions in case the client has
requested an unsupported version, and SHALL NOT be used for any other purpose.
Note that this restriction has been defined because this message may occur in place of any response.
resourceReference VersionedResource No A resource URL with associated version.

[1..unbounded]
Table 6: VersionedResourceList structure
The versionedResourceList element of type VersionedResourceList is defined as a root element in the XSD.
6.2.2 Enumerations
6.2.2.1 Enumeration: NotificationFormat

List of notification format values.
Enumeration Description
XML Notification about new inbound message would use XML format in the POST request

JSON Notification about new inbound message would use JSON format in the POST request
Table 7: NotificationFormat Values
6.2.2.2 Enumeration: RetrievalStatus

Enumeration Description
Retrieved Data retrieved. Current data is provided
NotRetrieved Data not retrieved, current data is not provided (does not indicate an error,
no attempt may have been made). Note that this field is useful in case a list
of addresses are requested, some items could be marked as
"NotRetrieved" in case retrieval could not be attempted for some reason,
e.g. to avoid time outs
Error Error retrieving data
Table 8: RetrievalStatus
6.3 Charging
This section deals with in-band charging, i.e. passing charging data as part of the RESTful Network API request. To enable
this capability to be provided across a variety of services in a consistent manner, the information to be provided in the
message for charging information is defined as a common charging data type.
6.3.1 Charging data type

The charging information is provided in an XML data type, using the following schema. See section 6.2.1.1 for the formal
definition.
<xsd:complexType name="ChargingInformation">
<xsd:sequence>
<xsd:element name="description" type="xsd:string" minOccurs="1" maxOccurs="unbounded"/>
<xsd:element name="currency" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="amount" type="xsd:decimal" minOccurs="0" maxOccurs="1"/>
<xsd:element name="code" type="xsd:string" minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
The application accessing the Service provides this information:

 “description” is an array of text. The first entry of a list will often be used to provide billing text. This text does not
have specific required content, but would likely include information on the business, the content or service provided,
and a transaction identifier. Credit card statements are a good example of description text provided by different
companies.
 When more than one entry is provided, the rest should be references to individual operations relevant to the charging.
Reference should be set to a value provided in a response message to the operation as a unique identifier to correlate
individual operation.
 “currency” in which the charge is to be applied. Values for the currency field are defined by [ISO4217].
 “amount” defines the amount to be charged.

 “code” specifies a charging code which references a contract under which this charge is applied. The code identifier is
provided by the Service Provider.
The charging information provided may not be acceptable to the Service Provider. For example, the Service Provider may
limit the amount that may be specified for a particular Service or for a particular Service Requester. If the information
provided is not acceptable, an appropriate fault message may be returned to the requester (SVC0007 and POL0012 are
defined as a generic charging fault, The ‘SVC’ and ‘POL’ service exceptions are defined in [ParlayX_Common]).
Especially in case of charging operation such as creating a charge or refund, it is strongly recommended to convey a list of
relevant operations related to charging over a description part as described above.
This is useful especially when a charging operation is performed after a certain set of operations.
Some of the services may be meaningful to the user only when a certain set of operations is completed. In that case, service
provider may want to charge a user only upon a completion of the entire process, instead of charging per operation. Also,
service provider may want to control the actual amount of charging depending on a certain condition, e.g., service usage
volume, independent of the volume control provided by the network operators. This is also the case where it is preferable to
perform charging operation after a completion of certain set of operations. In these cases where a service provider charges a
user for the consumption of a certain service, the service provider is recommended to provide the references to the individual
operations performed as evidences. This information can be referenced by the relevant entities to ensure the validity of
charging when necessary.
It should be noted that this is for a service provider to provide a list of evidences of their direct use of operations. Any
mapping of underlying operations performed internally in the operator must be performed by the operator if necessary. How
to maintain the consistency between the information kept at service provider and the operators is out of scope. Also, charging
aspects which do not relate to any operations are not covered.

7. Error Handling
7.1 HTTP Response Codes
Following is a list of often used HTTP response codes for RESTful Network APIs. The full set of HTTP response codes can
be found in [RFC2616]. The first line of each error code has been copied from [RFC2616]. The second line gives a short
informative explanation of the meaning of the error code. For a normative description of the error code see [RFC2616].
200 OK
The operation was successful.
201 Created
The operation was successful, and a new resource has been created by the request.
202 Accepted
The request has been accepted for processing, but the processing has not been completed (yet).
204 No Content
The operation was successful, and the response intentionally contains no data.
300 Multiple Choices
The requested resource corresponds to any one of a set of representations, each with its own specific location. In the
OMA RESTful Network APIs, this code is for instance used to signal the supported API versions in case an
unsupported version was requested for a particular resource.
303 See Other
The response to the request can be found under a different URI and can be retrieved using a GET method on that
resource.
304 Not Modified
The condition specified in the conditional header(s) was not met for a read operation.
400 Bad Request
In the original HTTP meaning, this error signals invalid parameters in the request. In OMA RESTful Network APIs, this
code is also used as the “catch-all” code for error situations triggered by a client request, for which no matching HTTP
error code exists.
401 Unauthorized
Authentication has failed, but the application can retry the request using authorization.
403 Forbidden
The server understood the request, but is refusing to fulfil it (e.g. because application doesn't have permissions to access
resource due to the policy constraints)
404 Not Found
The specified resource does not exist.
405 Method Not Allowed
The actual HTTP method (such as GET, PUT, POST, DELETE) is not supported by the resource
406 Not Acceptable
The content type requested is not acceptable for the resource.
408 Request Timeout
The client did not produce a response in the time the server was prepared to wait.
409 Conflict
Occurs in situations when two instances of an application are trying to modify a resource in parallel, in a non-
synchronized way.
410 Gone
The requested resource is no longer available at the server.

411 Length Required

The Content-Length header was not specified.
412 Precondition Failed
The condition specified in the conditional request header(s) was not met for an operation.
413 Request Entity Too Large
The size of the request body exceeds the maximum size permitted by the server implementation.
414 Request-URI Too Long
The length of the request URI exceeds the maximum size permitted by the server implementation.
415 Unsupported Media Type
The content type of the request body is unsupported by the server.
500 Internal server error
General, catch-all server-side error
503 Service Unavailable
The server is currently unable to receive requests, but the request can be retried at a later time.
7.2 Handling of not allowed HTTP methods

If a method is not allowed by the resource (error code 405), then server SHOULD also include the ‘Allow:
{GET|PUT|POST|DELETE} HTTP header in the response as per section 14.7 in [RFC2616].
7.3 HTTP Response Codes in Response to Notifications

Handling of HTTP response codes sent by the client application, in response to a notification from the server:
1. in case of HTTP 2xx response codes, server assumes the notification has been sent successfully.
2. in case of HTTP response codes other than 2xx, the handling is left to the server implementation. The server MAY
support different actions as dictated by a service provider policy (out-of-scope for this specification).

Appendix A. Change History (Informative)

A.1 Approved Version History
Reference Date Description
n/a n/a No prior version
A.2 Draft/Candidate Version 1.0 History

Document Identifier Date Sections Description
Draft Versions 12 Apr 2011 Many Structural changes to fit the OMA RESTful Network API release. This
OMA-TS-REST_NetAPI_Common-V1_0 version inherits the technical content of OMA-TS-
ParlayREST_Common-V1_1-20110111-C and OMA-TS-
REST_Common-V1_0-20110111-C.
It applies changes according to OMA-ARC-2011-0111R04 and OMA-

ARC-2011-0088R01.
15 Apr 2011 Some OMA-ARC-2011-0185-CR_Title_alignment_of_Common_TS applied.
1 Jul 2011 5.8, 5.9, 6.2 Incorporated:
OMA-ARC-REST-NetAPI-2011-0018R02-
CR_ApiVersion_in_TS_Common
OMA-ARC-REST-NetAPI-2011-0113-
CR_Fixing_Namespace_TS_Common
22 Sep 2011 2.1, 3.3, 6.1, Incorporated:

6.2 OMA-ARC-REST-NetAPI-2011-0249R01-CR_ACR_Common
6 Nov 2011 5.5.1 Incorporated:

CR_Common_versioning_text_changes_easy_part
CR_Common_TS_resourceURL_handling
21 Nov 2011 2.1, Appx D Incorporated:
OMA-ARC-Autho4API-2011-0045R02-
CR_Autho4API_support_in_REST_NetAPI_Common
28 Nov 2011 6.2.1 Incorporated:
CR_ResourceURL_in_Common
5 Dec 2011 5.8.1.1, Appx Incorporated:
D OMA-ARC-REST-NetAPI-2011-0433R02-
CR_ACR_Authorization_and_other_Autho4API_fixes
31 Jan 2012 5.5.2, Appx C Incorporated:
CR_Common_Exceptions_added_to_Common_TS
02 Feb 2012 Some Incorporated:
CR_ClientCorrelator_description_in_TS_Common
14 Feb 2012 Appx C Incorporated:
CR_Add_forgotten_exceptions_Common
CR_Moving_call_specific_stuff_from_Common_to_3PC_TS_Commo
n
CR_Common_TS_CONR_comments_resolution
21 Feb 2012 Appx B1.1 Incorporated:
CR_Common_TS_CONR_comment_A010_resolution
22 Feb 2012 5.9 Incorporated:
CONRR comment A029 resolution as agreed and recorded in OMA-
CONRR-REST_NetAPI_Common-V1_0-20120222-D

Document Identifier Date Sections Description

21 Mar 2012 5.8, 5.9, 6.2.1 Incorporated:
CR_Common_version_error_response
03 Apr 2012 Some Incorporated:
CR_Common_Adding_more_general_POL_and_SVC_codes
CR_Common_HTTP_code_example_bugfix
CR_Common_POL_resolution_for_FT_IS
04 Apr 2012 Section 2.1, OMA-ARC-REST-NetAPI-2012-0132R01-
3.1, Appendix CR_Common_TS_address_NetAPI_issue_18
D
Candidate Version 17 Apr 2012 n/a Status changed to Candidate by TP
OMA-TS-REST_NetAPI_Common-V1_0 TP Ref # OMA-TP-2012-0175-
INP_REST_NetAPI_Common_1_0_RRP_for_Candidate_Approval

Appendix B. Shared Definitions for Exception Handling in RESTful

Network APIs based on Parlay X (Normative)
This appendix defines building blocks for exception handling which are shared among those RESTful Network APIs which
have corresponding Parlay X [PSA] specifications as the baseline. These building blocks have been inherited and possibly
adapted from [ParlayX_Common].
RESTful Network APIs not having a Parlay X baseline can reference these as well if appropriate.
If an API re-uses the charging mechanism defined in section 6.3, this implies support for handling the RequestError type as
well.
B.1 Common data types for exception handling
B.1.1 Type: RequestError

link Link[0..unbounded] Yes Link to elements external to the resource
serviceException ServiceException Choice Exception Details
policyException PolicyException Choice Exception Details
Table 9: RequestError
A requestError element of type RequestError is defined as a root element in the XSD.

XSD modelling uses a “choice” to select either a serviceException or a policyException.
B.1.2 Type: ServiceException

messageId xsd:string No Message identifier, with prefix SVC
text xsd:string No Message text, with replacement variables marked with %n,
where n is an index into the list of <variables> elements, starting
at 1
variables xsd:string Yes Variables to substitute into Text string
[0..unbounded]
Table 10: ServiceException
B.1.3 Type: PolicyException

messageId xsd:string No Message identifier, with prefix POL
at 1
variables xsd:string Yes Variables to substitute into Text string
[0..unbounded]
Table 11: PolicyException

B.1.4 Type: ServiceError

In a response to a request, ServiceError is used when an operation involving multiple items fails for only some of the items,
whereas ServiceException is used where the entire operation fails.
In notifications, ServiceError is always used to indicate a notification termination or cancellation.

messageId xsd:string No Message identifier, either with prefix SVC or with prefix POL
at 1
variables xsd:string Yes Variables to substitute into text string
[0..unbounded]
Table 12: ServiceError
B.2 Handling of Service and Policy exceptions

In case of errors, additional information in the form of Exceptions MAY be included in the HTTP response.
Exceptions are defined with three data elements.
The first data element is a unique identifier for the message. This allows the receiver of the message to recognize the message
easily in a language-neutral manner. Thus applications and people seeing the message do not have to understand the message
text to be able to identify the message. This is very useful for customer support as well, since it does not depend on the reader
to be able to read the language of the message.
The second data element is the message text, including placeholders (marked with %) for additional information. This form is
consistent with the form for internationalization of messages used by many technologies (operating systems, programming
environments, etc.). Use of this form enables translation of messages to different languages independent of program changes.
The third data element is a list of zero or more strings that represent the content to put in each placeholder defined in the
message in the second data element with the first entry mapping to the placeholder %1.
B.2.1 Service exception

The Service exception is provided in an XML data type, using the following schema.
<xsd:complexType name="ServiceException">
<xsd:sequence>
<xsd:element name="messageId" type="xsd:string"/>
<xsd:element name="text" type="xsd:string"/>
<xsd:element maxOccurs="unbounded" minOccurs="0" name="variables" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
When a service is not able to process a request, and retrying the request with the same information will also result in a failure,
and the issue is not related to a service policy issue, then the service will issue a fault using the ServiceException fault
message. A Service Exception uses the letters 'SVC' at the beginning of the message identifier. General ‘SVC’ service
exceptions are defined in Appendix C.
Examples of Service exceptions include invalid input, lack of availability of a required resource or a processing error.

B.2.2 Policy exception

The policy exception is provided in an XML data type, using the following schema.
<xsd:complexType name="PolicyException">
<xsd:sequence>
<xsd:element name="messageId" type="xsd:string"/>
<xsd:element name="text" type="xsd:string"/>
<xsd:element maxOccurs="unbounded" minOccurs="0" name="variables" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
When a service is not able to complete because the request fails to meet a policy criteria, then the service will issue a fault
using the Policy Exception fault message. To clarify how a Policy Exception differs from a Service Exception, consider that
all the input to an operation may be valid as meeting the required input for the operation (thus no Service Exception), but
using that input in the execution of the service may result in conditions that require the service not to complete. A Policy
Exception uses the letters 'POL' at the beginning of the message identifier. General ‘POL’ service exceptions are defined in
Appendix C.
Examples of Policy exceptions include privacy violations, requests not permitted under a governing service agreement or
input content not acceptable to the service provider.

Appendix C. Common Exception Definitions (Normative)

Note: The exception codes from 0001 to 0999 are inherited from ParlayX [ParlayX_Common]. New exception codes defined
by the individual OMA RESTful Network APIs occupy the range from 1000 to 1999. New common exception codes for the
OMA RESTful Network APIs are defined in the range from 2000 to 2099. The range from 2100 – 2999 is reserved for future
use. The range from 3000 – 3499 can be used for experimental or private purposes; these values will not be assigned in a
specification.
C.1 Service Exceptions

Faults related to the operation of the service, not including policy related faults, result in the return of a ServiceException
message.
C.1.1.1 SVC0001: Service error

Name Description
MessageId SVC0001
Text A service error occurred. Error code is %1
Variables %1 Error code from service
HTTP status code(s) 400 Bad request
C.1.1.2 SVC0002: Invalid input value

Name Description
MessageId SVC0002
Text Invalid input value for message part %1
Variables %1 - message part
C.1.1.3 SVC0003: Invalid input value with list of valid values

Name Description
MessageId SVC0003
Text Invalid input value for message part %1, valid values are %2
%1 - message part
Variables
%2 - list of valid values
C.1.1.4 SVC0004: No valid address(es)

Name Description

MessageID SVC0004
Text No valid addresses provided in message part %1
HTTP status code(s) 404 Not found, 400 Bad request
If the address is part of the resource URL, the status code 404 SHOULD be used; otherwise the status code 400 SHOULD be
used.
C.1.1.5 SVC0005: Duplicate correlator

Name Description
MessageID SVC0005
Text Correlator %1 specified in message part %2 is a duplicate
Variables %1 - correlator
%2 - message part
HTTP status code(s) 409 Conflict
See section 5.5.2 for more information.
C.1.1.6 SVC0006: Invalid group

Name Description
MessageID SVC0006
Text Group %1 in message part %2 is not a valid group

%1 - identifier for the invalid group
Variables
%2 - message part
C.1.1.7 SVC0007: Invalid charging information

Name Description
MessageID SVC0007
Text Invalid charging information
Variables None

C.1.1.8 SVC0008: Overlapping Criteria

Name Description
MessageID SVC0008
Text Overlapped Criteria %1
Variables %1 Message part with the overlapped criteria
C.1.1.9 SVC1000: No server resources available to process the request

Name Description
MessageID SVC1000
Text No resources
Variables None
HTTP status code(s) 503 Service unavailable
C.1.1.10 SVC2000: Service Error

This is similar to SVC0001, however, it allows a more structured error handling by communicating two variables: a machine-
readable error code and an according human-readable description.
Name Description
MessageID SVC2000
Text The following service error occurred: %1. Error code is %2.
Variables %1 Description of the error

%2 Error code
C.2 Common Policy Exceptions

Faults related to policies associated with the service result in the return of a PolicyException message.
C.2.1.1 POL0001: Policy error

Name Description
MessageID POL0001
Text A policy error occurred. Error code is %1
Variables %1 Error code from service - meaningful to support, and may be documented in product
documentation

HTTP status code(s) 403 Forbidden
This exception represents a general, catch-all policy error. It can be used if no more information regarding the error is
available, or if it is not intended that the network shares more detailed information with the applicatiuon.
C.2.1.2 POL0002: Privacy error

Name Description
MessageID POL0002
Text Privacy verification failed for address %1, request is refused
Variables %1 - address privacy verification failed for
C.2.1.3 POL0003: Too many addresses

Name Description
MessageID POL0003
Text Too many addresses specified in message part %1
C.2.1.4 POL0004: Unlimited notifications not supported

Name Description
MessageID POL0004
Text Unlimited notification request not supported
Variables None
C.2.1.5 POL0005: Too many notifications requested

Name Description
MessageID POL0005
Text Too many notifications requested
Variables None

C.2.1.6 POL0006: Groups not allowed

Name Description
MessageID POL0006
Text Group specified in message part %1 not allowed
C.2.1.7 POL0007: Nested groups not allowed

Name Description
MessageID POL0007
Text Nested group specified in message part %1 not allowed
C.2.1.8 POL0008: Charging not supported

Name Description
MessageID POL0008
Text Charging is not supported
Variables None
C.2.1.9 POL0009: Invalid frequency requested

Name Description
MessageID POL0009
Text Invalid frequency requested
Variables None
C.2.1.10 POL0010: Retention time interval expired

Name Description
MessageID POL0010
Text Requested information unavailable as the retention time interval has expired.

Variables None
HTTP status code(s) 404 Not found, 410 Gone, 403 Forbidden
In case the information that has become unavailable is addressed by a resource URL, the following applies: If the resource
URL refers to a resource that has existed in the past and the server is aware of that fact, the status code 410 SHOULD be
used; otherwise (if the server is not aware), the status code 404 SHOULD be used.
In all other cases, the status code 403 SHOULD be used.
C.2.1.11 POL0011: Media Type not supported

Name Description
MessageID POL0011
Text Media type not supported
Variables None
HTTP status code(s) 406 Not acceptable, 403 Forbidden
If the media type was passed in the HTTP Accept header, the status code MUST be 406. Otherwise, it SHOULD be 403.
C.2.1.12 POL0012: Too many description entries specified

Name Description
MessageID POL0012
Text Too many description entries specified in message part %1
Variables %1 – message part
C.2.1.13 POL0013: Addresses duplication

Name Description
MessageID POL0013
Text Duplicated addresses
Variables %1 – duplicated addresses
C.2.1.14 POL1009: User not provisioned for service

Name Description
MessageID POL1009
Text User has not been provisioned for %1

Variables %1 – the name of the service
HTTP response 403 Forbidden
C.2.1.15 POL1010: User suspended from service

Name Description
MessageID POL1010
Text User has been suspended from %1
Variables %1 – the name of the service
C.2.1.16 POL1016: File size limit exceeded

Name Description
MessageID POL1016
Text File size exceeds the limit %1
Variables %1 – file size limit
C.2.1.17 POL2000: Policy Error

This is similar to POL0001, however, it allows a more structured error handling by communicating two variables: a machine-
readable error code and an according human-readable description.
Name Description
MessageID POL2000
Text The following policy error occurred: %1. Error code is %2.
Variables %1 Description of the error

%2 Error code

Appendix D. Deployment Considerations (Informative)
Applications using the RESTful Network APIs can be categorized by their execution environment:
 Application is a RESTful client application executing in a server execution environment (e.g. a 3rd party application).
 Application is a RESTful client application executing in a mobile device execution environment.
 Application is a RESTful client application executing in a fixed device execution environment.
 Application is a RESTful client application executing in a browser execution environment.
A RESTful Network API client can execute in any of the above execution environments.
Issues that are dependent on the execution environment and can impact strategic deployment decisions, interoperability, and
scalability include (non-exhaustive list):
 Security aspects (e.g. client application authentication)
 Delivery of notifications from server to client application. The mechanism for delivery of notifications may
depend on the execution environment of the client application. A non-exhaustive list of notifications
delivery mechanisms include:
 Notifications sent from server to client application, for example:
i. There must be an active "listener" on the application host (in this case the client device),
ready to receive the incoming notification via the HTTP protocol.
ii. This does not have to be the application itself, but at least some host service/client which
can invoke the specific application when needed.
iii. In a client-server HTTP binding, this requires that the client has the support of an HTTP
listener service.
 Notifications retrieved by the client application using Long Polling at a Server-side Notification
URL:
i. The client must have previously created a Notification Channel to obtain a Server-side
Notification URL and a URL on which to perform Long Polling [REST_Notif_Channel].
While solutions to particular issues related to the client application execution environment are out-of-scope for the RESTful
Network APIs, other OMA enablers should be re-used (where applicable) to address such particular issues.

D.1 RESTful client application executing in a server execution

environment
Figure 1 RESTful Network API accessed from a server execution environment (e.g. 3rd party Service Provider
application)
The RESTful Network API exposed by the server deployed in the Network Operator service layer domain, may be accessed
by a client application executing on a server resident in the Service Provider domain.This deployment can support all
resources and operations specified in the RESTful Network APIs. There are no particular issues with support of notifications
from a server to aclient application.
D.2 RESTful client application executing in a mobile device

execution environment

Figure 2 RESTful Network API accessed from a mobile device execution environment
The RESTful Network API exposed by a server deployed in the Network Operator service layer domain, may be accessed by
a client application executing on an end user mobile device. This deployment can support most resources and operations
specified in the API. There are however particular issues with support of notifications from server to client application:
 Typically in mobile devices, the client does not have the support for an HTTP listener service. The
specified client notifications may have to be delivered by alternative means. OMA Push
[OMA_PUSH] should be considered to be used to deliver the notifications to the client application.
 It must be possible to actually deliver the notification to the client application, i.e. there must be no
boundary across which the protocol is typically blocked. In a client-server HTTP binding, this will
typically be an issue as
o The client is typically within some private network behind a firewall (e.g. PLMN Operator
mobile network or home network)
o The client does not have a fixed IP address or an IP address that is resolvable via DNS.
o In such cases, a notification service such as OMA Push should be considered to be used to
bridge the firewall border and resolve the target address of the notification to an actual client
address.
D.3 RESTful client application executing in a fixed device

execution environment
Figure 3 RESTful Network API accessed from a fixed device execution environment
The RESTful Network API exposed by a server deployed on the Network Operator service layer domain, may be accessed by
a client application executing on a fixed device connected to the Network Operator.
This deployment can support most resources and operations specified in the API. Some issues with support of notifications
from server to client applications may be similar to those mentioned in Appendix D.2. Solutions to those issues may however
rely on other mechanisms (e.g. use of COMET).

Appendix E. Authorization aspects (Normative)

This appendix specifies how to use the OMA RESTful Network APIs in combination with some authorization frameworks.
E.1 Use of Autho4API

RESTful Network APIs MAY support the authorization framework defined in [Autho4API_10].
A RESTful Network API supporting [Autho4API_10] SHALL conform to this section D.1.
E.1.1 Endpoint URLs

The endpoint URL to which [Autho4API_10] compliant clients send authorization requests SHALL be constructed as
follows:
https://{serverRoot}/autho4api/{version}/authorize
The endpoint URL to which [Autho4API_10] compliant clients send token requests SHALL be constructed as follows:
https://{serverRoot}/autho4api/{version}/token
The endpoint URL to which [Autho4API_10] compliant clients send token revocation requests SHALL be constructed as
follows:
https://{serverRoot}/autho4api/{version}/revoke
Where the request URL variables are:
Name Description
server base url: hostname+port+base path. Port and base path are OPTIONAL.
serverRoot
Example: example.com/exampleAPI
version version of the [Autho4API_10] framework, SHALL be “v1” without quotes
These endpoints SHALL be able to serve the requests for authorizations and tokens for any OMA RESTful Network API
defining support for [Autho4API_10], and for any version of this RESTful Network API.
E.1.2 Scope values

E.1.2.1 Naming and registration
Autho4API scope values defined by OMA RESTful Network API specifications SHALL follow the {OMAScopeValue}
grammar defined in section 7.3.1.3 of [Autho4API_10], with the additional following constraints:
Name Description
ApiType fixed string “rest”
ApiIdentification identification of the OMA RESTful Network API (e.g. “messaging” without quotes)
identification of a set of operations on a set of resources of this API (e.g. “out”
Token without quotes), to be documented by the OMA RESTful Network API
specification
[Autho4API_10] scope values defined by OMA RESTful Network API specifications SHALL be registered with OMNA to
the OMNA Autho4API Scope Value Registry [OMNA_Autho4API].
E.1.2.2 Usage
The [Autho4API_10] compliant client SHALL include in the first request of the authorization protocol defined in
[Autho4API_10] the scope parameter containing a space-delimited list of scope values belonging to OMNA Autho4API

Scope Value registry. The Authorization Server SHALL return an error response containing the error code appropriate to the
protocol flow (e.g. “invalid_scope”) in the following cases:
 the scope parameter is missing;
 the requested scope is invalid, unknown, or malformed;
 the requested scope includes multiple scope values, and one of them is defined by the OMA RESTful Network API
for the issuing of one-time access tokens only.


Oma Ts Rest Netapi Common

Uploaded by

Copyright:

Available Formats

Oma Ts Rest Netapi Common

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Oma Ts Rest Netapi Common

Uploaded by

Copyright:

Available Formats

Common definitions for RESTful Network APIs

Candidate Version 1.0 – 17 Apr 2012

Open Mobile Alliance

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

B.2 HANDLING OF SERVICE AND POLICY EXCEPTIONS .................................................................................................. 32

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

2.2 Informative References

[REST_NetAPI_WP] “Guidelines for RESTful Network APIs”, Open Mobile Alliance™,

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

3. Terminology and Conventions

ACR Anonymous Customer Reference

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

URL Uniform Resource Locator

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

4.1 Version 1.0

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

5. Common Specifications for RESTful Network APIs

5.2 Unsupported Formats

5.3 Authoring Style

5.3.2 Case usage for names

5.4 Content type negotiation

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

5.5 Resource creation

5.5.2 Error recovery during resource creation

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

5.6 JSON encoding in HTTP Requests/Responses

c. The value is formed as follows:

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

 the first <?xml version="1.0" encoding="UTF-8" ?> tag

 declaration of namespaces or schemaLocations

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

5.6.2 Serialization rules: structure-aware conversion

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

5.6.3 Rules for JSON-creating and JSON-consuming applications

1. a pair of name and value (e.g. “name”: “one”)

2. a pair of name and array of one value (e.g. “name”: [“one”])

5.7 Encoding and Serialization Details for MIME format

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

Content-Type: <Corresponding Content type>

5.8 Resource URL considerations

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

5.8.2 API version signaling

5.8.3 Handling of unsupported versions

5.8.3.1 Example 1: Signalling supported versions in case an unsupported version

GET /exampleAPI/smsmessaging/v2/outbound/tel%3A%2B19585550151/requests HTTP/1.1

HTTP/1.1 300 Multiple Choices

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

Date: Thu, 04 Jun 2009 02:51:59 GMT

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

5.8.3.2 Example 2: Signalling supported versions in case an unsupported version

GET /exampleAPI/smsmessaging/v2/outbound/tel%3A%2B19585550151/requests HTTP/1.1

HTTP/1.1 300 Multiple Choices

5.9 Backward compatibility

 2012 Open Mobile Alliance Ltd. All Rights Reserved.

When processing an application/x-www-form-urlencoded [W3C_URLENC] data structure that contains name-value-pairs

 2012 Open Mobile Alliance Ltd. All Rights Reserved.