Doc# ioh1666215671.doc INPUT CONTRIBUTION Group Name:* ARC WG Title:* High level Application Programming Interface Source:* NEC(ETSI), Telecom Italia (ETSI), Sierra Wireless(ETSI), Interdigital Communication (TIA) Contact: Michele Lupano (michele.lupano@telecomitalia.it) Date:* 2013-06-18 Abstract:* This contribution introduces an high level API for all reference points The API controls the M2M Resource Model defined in chapter X Agenda Item:* Tbd Work item(s): M2M Architecture Document(s) Impacted* Architecture TS Intended purpose of document:* Decision requested or recommendation:* Decision Discussion Information Other For discussions and adoption in Functional Architecture Technical Specifications oneM2M IPR STATEMENT Participation in, or attendance at, any activity of oneM2M, constitutes acceptance of and agreement to be bound by all provisions of IPR policy of the admitting Partner Type and permission that all communications and statements, oral or written, or other information disclosed or presented, and any translation or derivative thereof, may without compensation, and to the extent such participant or attendee may legally and freely grant such copyright rights, be distributed, published, and posted on oneM2M’s web site, in whole or in part, on a non-exclusive basis by oneM2M or oneM2M Partners Type or their licensees or assignees, or as oneM2M SC directs © 2012 oneM2M Partners Page (of Doc# ioh1666215671.doc Introduction This contribution introduces an high level Application Programming Interface (API) applicable to all reference points The API controls the M2M defined Resource Model defined in chapter X Proposal =========================== 1st Change Informative References [i.x] Fielding, Roy Thomas (2000): "Architectural Styles and the Design of Network-based Software Architectures", Doctoral dissertation, University of California, Irvine =========================== 2nd1st Change X X and Y M2M high level Application Programming InterfaceReference Points X.1 Introduction The X and Y reference points procedures adopt a RESTful style This style governs how M2M Applications and/or M2M CSE are exchanging information with each other, transferring representations of uniquely addressable resources The principles of a RESTful style communication are described in [i.x] Procedures involving entities CSE and applications are executed by data exchange according to message flows described YX.4 The Ddata exchange consists of control and use case information transferred across the reference points and stored in standardized resource tree structures as described in X.3.Z Main purpose of a The use of addressable resources data structure is to facilitateis also enabling the “store-and-share” paradigm applied of application information to and big data also Access and manipulation of the resources is subject to their correlated permissions The chapter describes the high level data exchange for resource tree manipulation over a generic communication interface Some of the procedures of the X,Y reference points may not adopt the RESTful style described in this chapter (e.g for security and management) and are described in [reference to be included when available] Editors note: Which of the procedures not adopt the RESTful style described in this chapter and how there are performed is for FFS) X.2 Send and Receive General primitivescommunication Flow scheme X.2.1Description Figure X.1 shows the communication scenario used to describe general flows that govern the information exchange within a procedure, which is based the use of Send and Receive Response scheme The scheme applies to communications © 2012 oneM2M Partners Page (of Doc# ioh1666215671.doc - between an Application and a CSE (X reference point) and - between two CSE (Y reference point) The communications can be initiated by both applications and CSEs.primitives Issuer Receiver Application Entity Send Resource tree storage Response Receive Figure X.1: Resource tree manipulation by an application to an entity Issuer Receiver Application Entity Send Resource tree storage Receive Message flows of procedures involving resources shall use the Send and Receive primitives X.2.21 Send primitive RSend requests from an Issuer to a Receiver through a communication interface shall be sent using the Send primitive with the following parametersincludes the following information: op: operation to be executed: Create (C), Retrieve (R), Update (U), Delete (D) to: address of target resource, e.g http://m2m.provider1.com:9000/netBase/temp1 fr: address of resource representing the Issuer as a known application or entity, used for access control, e.g http://m2m.provider2.com:9000/remBase/app1 hd: headers containing meta-information about the request cn: resource content to be transferred © 2012 oneM2M Partners Page (of Doc# ioh1666215671.doc A correctly received Send primitive shall be delivered to Receiver with no additional parameters The op parameterinformation shall indicate the operation to be executed in the receiver: • Create (C): a new resource addressable with to parameter is created • Retrieve (R): an existing to addressable resource is read and provided back to the Issuer • Update (U): the content of an existing to addressable resource is replaced with cn new content • Delete (D): an existing to addressable resource and all its subresources are deleted from the tree The to parameter information shall address the target resource in the Receiver even for Create operation, in that case the name of the new resource shall be the last token of to address, the remaining part is the parent resource address The fr parameter information shall be used by the Receiver to check the Issuer identity for access control permission purposesverification The cn parameter information shall be present in Send primitive in the following operations: • Create: cn is the content of the new resource • Update: cn is the content to be replaced in an existing resource • Retrieve: cn is the filter to be applied for discovery purposes The type of a created resource is semantically defined in its content cn For simplicity and safety reasons no resource expiration time is applicable, resources and their sub-trees shall be explicitly deleted by an allowed Issuer X.2.2Receiver processing Once the Send primitive is delivered to the Receiver shallit means that the data transfer to it has been successful and the requested operation shall be executed in the addressed entity that shall perform the following steps before to send a Receive primitive to the Issuer: • Check the existence of to addressed resource • Check the existence of fr resource Issuer • Analysis of cn content attribute, iIdentifying the resource type • Check the permission for fr Issuer to perform the requested operation with cn content when provided • Performs the requested operation (using cn content when provided) • Retrieve when requested the addressed resource data or other aggregated data to be sent to the Issuer • Preparation ofRespond to the Receiver primitive for successful or unsuccessful operation results • Delivery of Receiver primitive © 2012 oneM2M Partners Page (of Doc# ioh1666215671.doc The message flow procedure started with an Issuer request shall be considered closed when a ReceiveResponse primitive is delivered to the Issuer X.2.32 Successful Receive response primitive Response from a Receiver to a Issuer through includes the following information: Send function shall require the provision of the following parameters: op: operation being executed: Create (C), Retrieve (R), Update (U), Delete (D) (optional) hd: headers containing meta-information about the request rs: operation result: e.g Okay, Okay and Done; Okay and Scheduled; Okay and In Progress, etc (O) cs: optional additional result information, e.g HTTP status codes to: address of target resource, e.g http://m2m.provider1.com:9000/netBase/temp1 cr: resource creation timestamp, e.g 2013-05-30T12:23:56 lm: resource last modified timestamp, e.g 2013-05-30T12:23:56 cn: resource content to be transferred (optional) The to parameter shall confirm the address of the resource subjected to a successful operation The cn parameter information shall may be present in Receive primitivea response in the following operationscases: • Update: cn is the content replaced in an existing resource • Delete: cn is the content actually deleted The cn information shall be present in a response in the following cases: • Retrieve: cn is the retrieved resource content or aggregated contents of discovered resources • X.2.42 Unsuccessful Receive response primitive Response from a Receiver to a Issuer through includes the following information: Send function shall require the provision of the following parameters: op: operation being executed: Create (C), Retrieve (R), Update (U), Delete (D) (optional) hd: headers containing meta-information about the request rs: operation result: e.g Not okay (N) cs: optional additional result information, e.g HTTP status codes © 2012 oneM2M Partners Page (of Doc# ioh1666215671.doc X.3 Resource structure X.3.1 Introduction This section introduces the main types of resource used in a CSE A hierarchical tree scheme is used for modelling their structure and relationships X.3 Resource content representation Resources stored in a resource tree data structure contain both control and application classes of data that shall coexist in cn content attribute Resource content attribute cn shall be represented using XML notation satisfying the cohabitation of mentioned classes of data Send and Receive primitives and also Issuer and Receiver actors shall be able to operate using basic XML representation avoiding the verbose use of XSD schemas Being obvious the use of XML representation, then cn content resource attribute shall contain essential information, for this reason the following declarations can be avoided: …… essential information + XSD prefixes An example of XML representation with essential information only is provided: …… …… X.4 Resource type mapping As anticipated in clause X.2.1 the resource type involved in operations executed on resource tree is semantically defined in the content attribute cn that shall be defined with following representation: …… …… © 2012 oneM2M Partners Page (of Doc# ioh1666215671.doc where tag type shall be mapped for defined resource types as described in the following table that is showing even some virtual resources that are out of resource tree Table X.1: Resource types and taggingmapping Resource type Tag value NoteDescription Base b Real resource in a tree EntityCSE e Real resource in a tree Application a Real resource in a tree Access Right r Real resource in a tree Container c Real resource in a tree Subscribe s Real resource in a tree Group g Real resource in a tree Filter f Virtual resource out of tree, used to describe a filter criteria for discovery purposes Notify n Virtual resource out of tree, used for notification purposes Bulk k Virtual resource out of tree, used for group oriented bulk operations E.g when a Receiver looks for a cn content attribute starting as follows, then it recognizes a container resource: …… …… The inner tags of a resource representation will be described in procedure mapping clause Editor note: the content of this table is only an initial draft proposal X.4 Procedure description Editor note: this section is meant to describe the procedures and their related stage information flows © 2012 oneM2M Partners Page (of ... X and Y M2M high level Application Programming InterfaceReference Points X.1 Introduction The X and Y reference points procedures adopt a RESTful style This style governs how M2M Applications...Doc# ioh1666215671.doc Introduction This contribution introduces an high level Application Programming Interface (API) applicable to all reference points The API controls the... paradigm applied of application information to and big data also Access and manipulation of the resources is subject to their correlated permissions The chapter describes the high level data exchange