040 restful bindings physicalapis

7/27/2019 040 RESTful Bindings PhysicalAPIs

1/22

www.scf.io/ www.smallcellforum.org

RELEASE

DOCUMENT

RESTful Bindings

FemtoZone Services physical API realisation

April 2012

040.01.01

SMALL CELL FORUM

One scf.io/


2/22

Small Cell Forum supports the wide-scale adoption of small cells. Its mission is

to accelerate small cell adoption to change the shape of mobile networks and

maximise the potential of the mobile internet.

Small cells is an umbrella term for operator-controlled, low-powered radio accessnodes, including those that operate in licensed spectrum and unlicensed carrier-grade

Wi-Fi. Small cells typically have a range from 10 metres to several hundred metres.These contrast with a typical mobile macrocell that might have a range of up to several

tens of kilometres. The term small cells covers femtocells, picocells, microcells andmetrocells.

Small Cell Forum is a not-for-profit, international organisation, with membership opento providers of small cell technology and to operators with spectrum licences for

providing mobile services.

At the time of writing, the Small Cell Forum has 141 members including 68 operators

representing more than 3 billion mobile subscribers 46 per cent of the global total as well as telecoms hardware and software vendors, content providers and innovativestart-ups.

The Small Cell Forum is technology-agnostic and independent. It is not a standards-setting body, but works with standards organisations and regulators worldwide to

provide an aggregated view of the small cell market.

This document forms part of the Small Cell Forums Release One which addresses the

full range of applications for small cells: Home, Enterprise, Metro, Rural. The maintheme of Release One is the Home, and includes the complete body of work operators

will need to know for wide-scale deployment of femtocells intended for home or smalloffice applications. These applications are based typically indoors and involve locations

where a single femtocell is usually sufficient. Both 3GPP and 3GPP2 femtocells areincluded.

Release One also contains works clarifying market needs and addressing barriers to

deployment of enterprise, metro and rural small cells.

The Small Cell Forum Release website can be found here www.scf.io. A description and

roadmap for the release programme can be found here www.scf.io/doc/100

If you would like more information about the Small Cell Forum or would like to

be included on our mailing list, please contact:

Email [email protected]

Post Small Cell Forum, PO Box 23, GL11 5WA UK

Member Services Lynne Price-Walker [email protected]

For a full list of members and further information visit our websitewww.smallcellforum.org


3/22

Report title: RESTful Bindings

Issue date: 04 April 2012Version: 040.01.01

Scope

This document specifies the physical API realisation in support of the FemtoZone Service requirements forRelease One as defined by the Small Cell Forum [1].

The Small Cell Forum has chosen to re-use the standardised API definitions developed by GSMA OneAPI.This includes the SMS, MMS and terminal location APIs. To support the notion of a FemtoZone (defined in

[1]), an additional Zonal Presence has been defined.

This document references the existing OneAPI services. Additionally, it provides a proposed RESTful

interface definition for the Zonal Presence API. Small Cell Forum member companies placed a priority on aRESTful interface with XML or JSON payloads. As required, the following API variants may be defined:

Web Service (SOAP)NOTE: The Zonal Presence API realisation defined in this document maps to the Femto Awareness APIidentified in [1]. This is reflective of the API that has been designed to support other access types over and

above femtocells.


4/22

Contents

1. Introduction .................................................................... 1

1.1 FemtoZone Services Release 1 ............................................. 11.1.1 Zonal Presence API ............................................................. 1

1.1.2 SMS API............................................................................ 1

1.1.3 MMS API ........................................................................... 1

1.1.4 Terminal Location API ......................................................... 1

2. Zonal Presence Overview ................................................. 1

2.1 Definitions ......................................................................... 1

2.2 Use Cases ......................................................................... 2

2.2.1 FemtoZone Commercial Retail Loyalty Programs .................. 22.2.2 Information Freeway Zone ................................................... 2

3. Zonal Presence API Definition SOAP ............................. 2

4. Zonal Presence API Definition RESTful .......................... 2

4.1 Methods ............................................................................ 2

4.2 URIs ................................................................................. 3

4.3 Zonal Presence Subscription ................................................ 3

4.3.1 Initiate Subscription to Zonal Presence Notifications ................ 3

4.3.2 Cancel Subscription to Zonal Presence Notifications ................ 4

4.3.3 Zonal Presence Notification .................................................. 5

4.4 Query Zone List ................................................................. 6

4.5 Query Zone Status ............................................................. 6

4.6 Query a Namec Set of Access Point Status ............................. 7

4.7 Query Users Within a Zone .................................................. 8

5. Response Codes HTTP response codes are used toindicate: .......................................................................... 9

6. Zonal Presence XSD ....................................................... 10

6.1 OMA-SUP-XSD_rest_zonalpresence.xsd ................................ 10

6.2 OMA-SUP-XSD_rest_common-V1_1-20110111-C.xsd ............. 13

References ............................................................................... 18


5/22


Issue date: 04 April 2012Version: 040.01.01 1

1. Introduction1.1 FemtoZone Services Release One1.1.1 Zonal Presence APIThe Zonal Presence API provides a subscription mechanism where authorized applications can receive

notifications of user activities within a zone. As defined in 2.1, a zone is a set of access pointsrepresenting an entity, such as a chain store or shopping mall. Zonal Presence notifications are produced by

this API as follows:

Zone Enter When a mobile device transitions to an access point within the zone from one thatis external to the zone.

Zone Exit When a mobile device transitions to an access point external to the zone from onethat is within the zone.

Zone Transfer Upon transitioning between two access points within the zone.Additionally, the Zonal Presence API defines operations where applications can gain information aboutmobile devices in the zone, as well as the status of the zone and access points within. Refer to Chapter 2

Zonal Presence Overview and Chapter 4 Zonal Presence API Definition RESTful for more information.

1.1.2 SMS APIThe OneAPI SMS interface allows applications to send and receive SMS messages. The Zonal Presenceimplementation may restrict SMS message interactions then when mobile devices are in a zone associated

to the application

SMS SOAP http://www.gsmworld.com/oneapi/documents/OneAPI_WSDLs_v1/sms.zip SMS RESTful http://www.gsmworld.com/oneapi/documents/SMS-RESTful-API-V1.0f.pdf

1.1.3 MMS APIThe OneAPI MMS interface allows applications to send and receive MMS messages. The Zonal PresenceZonalPresence implementation may restrict MMS message interactions then when mobile devices are in a zone

associated to the application.

MMS SOAP http://www.gsmworld.com/oneapi/documents/OneAPI_WSDLs_v1/mms.zip MMS RESTful http://www.gsmworld.com/oneapi/documents/MMS-RESTful-API-V1.0.pdf

1.1.4 Terminal Location APIThe OneAPI location interface allows an application to query the location of one or more mobile devices thatare connected to an operator network. The Zonal Presence implementation may restrict location queries to

when mobile devices are in a zone associated to the application.

Location SOAP http://www.gsmworld.com/oneapi/documents/OneAPI_WSDLs_v1/location.zip Location RESTful http://www.gsmworld.com/oneapi/documents/Location-RESTful-API-V1.0.pdf

2. Zonal Presence Overview2.1 Definitions

Zone In the context of this document, a zone is defined by the aggregate coverage area of aset of wireless access points that may or may not have overlapping coverage. The set of accesspoints included in a zone is provisioned in the mobile operator network. The access point types

included in a zone may include any wireless access technology. This includes one or more of thefollowing (though not limited to the list below):

o 3G Base Stationso Femtocellso Wi-Fio WiMaxo LTE


6/22



Zonal Presence A presence indication where an application is aware of:o Mobile devices within the zoneo The particular access point that a mobile device is camped onto.

Zonal Presence Notifications Occur when a mobile device enters, exits or moves betweenaccess points within a zone at the point when it camps onto another access point. Third partyapplications subscribe to zonal presence notifications via an operator gateway API.

2.2 Use Cases2.2.1 FemtoZone Commercial Retail Loyalty ProgramsTo realize an in-store loyalty program, a chain store can deploy femtocell access points to their locationsnationwide. The stores zone will include all of these femtocells. Through the Zonal Presence API exposed

on an operators (or WAC) application gateway, an application will subscribe to zonal presence notifications.

Customers entering the zone will trigger a notification to the application, providing a window of opportunitywhere the application may interact with the customer while in the store via other OneAPI services.

2.2.2 Information Freeway ZoneTo an operator, the cost of data to and from mobile devices can vary greatly depending on access point

type. Mobile devices camped onto a femtocell or Wi-Fi will use an ISP for backhaul instead of consuming anoperators precious bandwidth and equipment resources in the macro network. The data costs are reduced

while offering possibilities of higher realistic bandwidth.

A Zone can be created around access points possessing spare bandwidth and high data rates. This could

encompass WiMax, Wi-Fi and/or femtocells. When a mobile device camps onto one of these access points, itcould be offered a host of bandwidth intensive services are very attractive rates. For example, a deferred

video download application may allow a user to select a movie for future download. Only when the mobiledevice camps onto an Information Freeway Zone will the download commence.

3. Zonal Presence API Definition SOAPSmall Cell Forum has defined a RESTful Zonal Presence API based on the demands of member companies.As required by Small Cell Forum members, or through standardization efforts by other industry bodies, a

SOAP variant may be defined.

4. Zonal Presence API Definition RESTfulThis section defines a RESTful interface (with XML and JSON payloads) for the Zonal Presence API in terms

of HTTP URIs used to invoke the operations, as well as example messages and responses for eachoperation. A XML schema is defined in chapter 6 to formally describe the XML content of the various

messages. There is no standard JSON equivelant to an XML schema. As such, the structure and content ofthe JSON documents described in this document map directly to the XML counterparts. As such, the XML

schema can used as a reference to validate JSON documents.

4.1 MethodsZonal Presence may be accessed via a REST API. The following methods are available:

Initiate Subscription to Zonal Presence Notifications Zonal Presence Notification Query Zone List Query Zone Status Query a named set of Access Point Status Query all Access Point Status Query a User within a Zone Query all Users on an Access Point Query all Users within a Zone


7/22



POST is used to initiate the subscription, DELETE is used to cancel the subscription and GET is used to

retrieve the status of users, access points and zones. PUT is not used. The URIs used in the Zonal PresenceAPI are as follows.

4.2 URIs Initiate the subscription to receive zonal presence notifications of users entering, existing or

transferring between access points within a zone:

http://example.com/{api version}/zonalpresence/subscriptions/{zoneId}

Cancel the subscription to zonal presence notificationshttp://example.com/{apiversion}/zonalpresence/subscriptions/{zoneId}/{subscriptionId}

Query to retrieve a list of zones the application is authorized to usehttp://example.com/{api version}/zonalpresence/queries/zone

Query to retrieve the status of a zone and relevant statisticshttp://example.com/{api version}/zonalpresence/queries/zoneStatus?zoneId={zoneId}

Query a named set of access point status in a zonehttp://example.com/{api version}/zonalpresence/queries/accessPointStatus?zoneId={zoneId}&accessPointId={accessPointId}

Query to retrieve the status of all access points in a zonehttp://example.com/{api version}/zonalpresence/queries/accessPointStatus?zoneId={zoneId}

Query to retrieve the status of a user within a zonehttp://example.com/{api version}/zonalpresence/queries/userStatus?zoneId={zoneId}&address={address}

Query to retrieve the status of all users within an access pointhttp://example.com/{api version}/zonalpresence/queries/userStatus?zoneId={zoneId}&accessPointId={accessPointId}

Query to retrieve the status of all users within a zonehttp://example.com/{api version}/zonalpresence/queries/userStatus?zoneId={zoneId}

NOTES: example.com is replaced by the hostname of the OneAPI server you are accessing. api versionindicates the version of Zonal Presence you are accessing.

4.3

Zonal Presence Subscription

4.3.1 Initiate Subscription to Zonal Presence NotificationsRequest Description

XML BodyPOST

http://example.com/1/zonalpresence/subscriptions/yumscoffeeHTTP/1.1

Host: example.com:80Content-Type: application/x-www-form-urlencoded

Accept: application/xml

Use POST to create the messagesubscription for the yumscoffee zone.

Mandatory parameters:notifyURL (URL) This will be used by

the server to POST the notifications toyou, so include the URL of your own

listener application.

Optional parameters:


8/22



http://www.yoururl.here/notifications/

doSomething

XML

12345

JSON Body

POSThttp://example.com/1/zonalpresence/subscriptions/yumscoffee

HTTP/1.1Host: example.com:80

Content-Type: application/jsonAccept: application/json

{zonePresenceSubscribe: {

callbackReference: {notifyURL: http://www.yoururl.here/notification/,

callbackData: doSomething,

notificationFormat: XML},

clientCorrelator: 12345

}}

clientCorrelator (string) uniquely

identifies this create subscriptionrequest. If there is a communication

failure during the request, using the

same clientCorrelator when retrying therequest allows the operator to avoid

creating a duplicate subscription.

callbackData (string) is a function nameor other data that you would like

included when the POST is received.

notificationFormat (string) Application

can specify format of the resourcerepresentation in notifications that are

related to this subscription. The choiceis between {XML, JSON}.

Successful Response Description

XML BodyHTTP/1.1 201 Created

Content-Type: application/xmlLocation: http://example.com/1/zonalpresence/

Date: Thu, 04 Jun 2009 02:51:59 GMTContent-Length: 1024

http://www.yoururl.here/notifications>

doSomething

http://example.com/1/zonalpresence/subscriptions/yumscoffee/12345

JSON Body

HTTP/1.1 201 CreatedContent-Type: application/jsonLocation: http://example.com/1/zonalpresence/

subscriptions/yumscoffee/12345Date: Thu 04, June 2009 02:51:59 GMT

Content-Length: 1024{

deliveryReceiptSubscription: {

callbackReference: {notifyURL: http://www.yoururl.here/notification/,

callbackData: doSomething,notificationFormat: XML

},clientCorrelator: 12345,

resourceURL:http://example.com/1/zonalpresence/subscriptions/yumscoffee/12345

}

A 201 response indicates thesubscription has been created at the

URI in the Location header. sub01indicates the subscription ID that will be

used when cancelling the subscription.

The XML response body simply confirmsthe creation of the subscription and theURL it will POST notifications to.

Mandatory parameters:

notifyURL (URL) This will be used bythe server to POST the notifications to

you, so include the URL of your ownlistener application.

Optional parameters:clientCorrelator (string) uniquely

identifies this create subscriptionrequest. If there is a communication

failure during the request, using the

same clientCorrelator when retrying therequest allows the operator to avoidcreating a duplicate subscription.

callbackData (string) is a function nameor other data that you would like

included when the POST is received.

notificationFormat (string) Application

can specify format of the resourcerepresentation in notifications that are

related to this subscription. The choiceis between {XML, JSON}.


9/22



}

4.3.2 Cancel Subscription to Zonal Presence NotificationsRequest Description

DELETEhttp://example.com/1/zonalpresence/subscriptions/yumscoffee/

12345 HTTP/1.1Host: example.com:80

Accept: application/xml or application/json

Deletes the subscription for theyumscoffee zone. sub01 is the

subscription ID provided in the responseto the subscription.


HTTP/1.1 204 No Content

Date: Thu, 01 Feb 2011 12:00:00 GMT

Successful deletion of the subscription.

4.3.3 Zonal Presence NotificationNotification Description

XML Body2012-04-03T23:17:33.720

04:00

YumsCoffee

2012-04-03T23:17:33.722

04:00+16131234567

femto156

2012-04-03T23:17:33.722

04:00+16131234000

femto157

2012-04-03T23:17:33.72204:00

+16131234000

femto156femto157

doSomething

When a zonal presence subscription isset up, the oneAPI will send zonal

presence notifications to the notify-url

passed in the subscription request.

The zonal-presence-notification elementincludes any callbackData, time of day

and zone-id. For each user, it containsthe following:

event-id: enter, exit ortransfer.

user-address: the usersMSISDN or anonymous

customer reference (ACR)

access-point: elementcontaining the current accesspoint ID and/or previous

access point ID (dependingon the value of the event-id.

To reduce notification volumes,numerous user-events may be bundled

in a single notification. An applicationgateway may define a maximum latency

for reporting zonal presence notificationand include all the user-events within

that period.


10/22



JSON Body

POST http://www.yoururl.here/notification/Content-Type: application/json

Content-Length: 1234

{zonePresenceNotification: {

callbackData: doSomething,timestamp: 2011-02-01T12:00:00,

zoneId: yumscoffee,userEvent: [

{timestamp: 2011-02-01T12:00:00,

address: tel:+16131234567, zoneEnter: {currentAccessPoint: femto01

}},

{timestamp: 2011-02-01T12:00:00,

address: tel:+16131234000, zoneExit: {currentAccessPoint: femto02

}

},{timestamp: 2011-02-01T12:00:00,

address: tel:+16131235000,zoneTransfer: {

currentAccessPoint: femto02,previousAccessPoint: femto01

}}

]}

}

4.4 Query Zone ListRequest Description

GET http://example.com/1/zonalpresence/queries/zone/HTTP/1.1 Host: example.com:80 Accept: application/xml or

application/json

Use GET to get a list of identifiers forzones authourized for use by the

application.


XML Body

HTTP/1.1 200 OKContent-Type: application/xml

Content-Length: 1000Date: Thu, 04 Jun 2009 02:51:59 GMT

yumscoffee

yumsmuseum

JSON Body

HTTP/1.1 200 OKContent-Type: application/json

Content-Length: 1024Date: Thu 04, June 2009 02:51:59 GMT

{zoneList: {

zone: [

Returns 200 OK if the operation is

successful. The response will include alist of zone elements containing

identifying zones that the application isauthorized to use.


11/22



{

zoneId: yumscoffee},

{

zoneId: yumsmuseum}

]}

}

4.5 Query Zone StatusRequest Description

GEThttp://example.com/1/zonalpresence/queries/zone?zoneId=yum

scoffee HTTP/1.1Host: example.com:80 Accept: application/xml or

application/json

Use GET to get a zone status. The zone-id is passed as an attribute in the HTTP

request.


XML Body

HTTP/1.1 200 OKContent-Type: application/xml


YumsCoffee

3612

1

JSON BodyHTTP/1.1 200 OK

Content-Type: application/jsonContent-Length: 1024

Date: Thu 04, June 2009 02:51:59 GMT{ zoneStatus: {

zoneId: yumscoffee,numberOfUsers: 36,

numberOfAccessPoints: 12,

numberOfUnserviceableAccessPoints: 1}}

}

Returns 200 OK if the operation is

successful. The response will includethe:

zone-id: As passed in therequest.

num-users: Number of userscurrently camped onto theaccess points within the zone

num-access-points Thenumber of access points

within the zone.

Num-unserviceable-access-points: The number of

inoperable access pointswithin the zone.

4.6 Query a Named Set of Access Point StatusRequest Description

Case1: Status for a named set of access points

GET http://example.com/1/zonalpresence/queries/

accessPointStatus?zoneId=yumscoffee&accessPointId=femto01

HTTP/1.1

Access point status can be retrieved for

sets of access points matching attributein the request.

Case 1: Status for a named set of


12/22



Host: example.com:80


Case2: Status for ALL access points within the zone:

GET http://example.com/1/zonalpresence/queries/

accessPointStatus?zoneId=yumscoffee&accessPointId=femto01HTTP/1.1

Host: example.com:80Accept: application/xml or application/json

access points the following attributes

are added in the request:

zoneId accessPointId: One or more

access point attributes

Case 2: Status for all access pointswithin the zone simply pass the

zoneId attribute in the request.


XML BodyHTTP/1.1 200 OK

Content-Type: application/xml


90.123

80.12310.0

0

femtoServiceable

femto-10010

91.123

81.12312.0

1

femtoUnserviceable

femto-10115

YumsCoffee

JSON Body

HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 1024

Date: Thu 04, June 2009 02:51:59 GMT{

accessPointStatusList: {zoneId: yumscoffee,

accessPointStatus: [{

accessPointId: femto01,accessType: femto,

numberOfUsers: 16,

operationStatus: SERVICEABLE,locationInfo: {

longitude: -79.630554,

latitude: 43.677223,altitude: 100.0,

The response will contain an access-point-status-list element that will

contain a set of access-point-status

elements, each containing:

access-point-id: the uniqueID for the access point.

access-type: One of femto,LTE-femto, Wi-Fi, Wimax

num-users: the number ofusers currently on the access

point. state: SERVICABLE or

UNSERVICEABLE timezone=the timezone the

access point is currentlylocated.

access-point-location(optional): The coordinatesof the access point (which

may serve as a roughlocation proxy to users

camped onto the accesspoint.


13/22



accuracy: 10.0

}}

]

}}

4.7 Query Users Within a ZoneRequest Description

Case 1: Query Zone for a specific user

GEThttp://example.com/1/zonalpresence/queries/userStatus?

zoneId=yumscoffee&address=tel:+16131234000 HTTP/1.1Host: example.com:80


Case 2: Query for a list of users on a given accesspoint:


zoneId=yumscoffee&accessPointId=femto02 HTTP/1.1Host: example.com:80


Case 3: Query all Users within a zone:


zoneId=yumscoffee HTTP/1.1Host: example.com:80


Users currently using a zone may be

retrieved for sets of access points matchingattribute in the request.

Case 1: Query for a specific user thefollowing attributes are added in the request:

zoneId address: The user MSISDN, or

Anonymous Customer Reference

(ACR).

Case 2: Query for users on a given access

point the following attributes are added tothe request:

zoneId accessPointId

Case 3: Query all users within the zone

simply pass the zoneId attribute in the

request.


XML BodyHTTP/1.1 200 OK

Content-Type: application/xmlContent-Length: 1000

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

+16131110000femto-0

+16131111111

femto-1

+16131112222

femto-2

JSON Body

HTTP/1.1 200 OKContent-Type: application/json

Content-Length: 1024

The response will contain an user-status-listelement that will contain a set of user-status

elements, each containing:

address: The identity of the user,either a MSISDN or AnonymousCustomer Reference (ACR).

access-point-id: The identity ofthe access point the user is

currently on.


14/22



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

{userStatusList: {

zoneId: yumscoffee,

userStatus: [{

address: tel:+16131234000,accessPointId : femto02

},{

address: tel:+16131235000,accessPointId : femto02

},{ address: tel:+16131234567,

accessPointId : femto01}

]}

}

5. Response Codes HTTP response codes are used to indicate: 200 Success 400 Bad request; check the error message for details 401 Authentication failure, check your authentication details 403 Forbidden; please provide authentication credentials 404 Not found: mistake in the host or path of the service URI 405 Method not supported: for example, you mistakenly used a HTTP GET instead of a POST 500 The server encountered an unexpected condition. This could be incorrect authentication

details or limited user permission

503 Server busy and service unavailable. Please retry the request.For more details on these,refer to http://www.ietf.org/rfc/rfc2616.txt.

6. Zonal Presence XSD6.1 OMA-SUP-XSD_rest_zonalpresence.xsd

This schema defines the XML for validating data used in the zonalpresence enabler.

Payload for a zonal presence subscription request.


15/22



Payload in the successful response of a zonal presence subscriptionrequest.

Payload for a zonal presence notification that will follow a successfulzonal presence subscription request.


16/22



Payload for a response to a zone status queryrequest.

Response to a query zone users request.

Response to a query access point status request.


17/22



6.2 OMA-SUP-XSD_rest_common-V1_1-20110111-C.xsd


18/22


19/22



This schema defines the XML for validating data used in the common partof all REST enablers.


20/22




21/22




22/22


Issue date: 04 April 2012

References

1 Small Cell Forum FemtoZone Services API (Release One) Operational Specification: APIsSupporting Femto Enhanced Applications available on the Small Cell Forum members site

2 Aepona "Universal Services Platform Telecom Web Services 3.3 Femto Zonal Presence RESTDocument Version: 1.0"

http://oneapi.aepona.com/f/files/Aepona_V1_0_Femto_Zonal_Presence_REST.pdf

040 restful bindings physicalapis

Documents