You are on page 1of 21

UNIVERSAL SERVICE PLATFORM 3.

3
TELECOM WEB SERVICES 3.4
FEMTO
ZONAL PRESENCE REST V1.0
DOCUMENT VERSION: 1.1

Copyright
2012
Aepona Limited,
Interpoint Building,
20-24 York Street,
Belfast BT15 1AQ

All rights reserved. This document or any part thereof may not, without the written consent of Aepona Limited, be
copied, reprinted or reproduced in any material form including but not limited to photocopying, transcribing,
transmitting or storing it in any medium or translating it into any language, in any form or by any means, be it
electronic, mechanical, xerographic, optical, magnetic or otherwise.
The information contained in this document is proprietary and confidential and all copyright, trademarks, trade names,
patents and other intellectual property rights in the documentation are the exclusive property of Aepona Limited unless
otherwise specified. The information (including but not limited to data, drawings, specification, documentation, software
listings, source or object code) shall not at any time be disclosed directly or indirectly to any third party without Aepona
Limiteds prior written consent.
The information contained herein is believed to be accurate and reliable. Aepona Limited accepts no responsibility for
its use by any means or in any way whatsoever. Aepona Limited shall not be liable for any expenses, costs by damage
that may result from the use of the information contained within this document. The information contained
herein is subject to change without notice.

Zonal Presence REST V1.0

Document Version: 1.1

Table of Contents
1

Zonal Presence REST Overview....................................................................................................5

Authentication..................................................................................................................................5

Methods............................................................................................................................................5
3.1

URIs................................................................................................................................................6
Initiate Subscription to Zonal Presence Notifications.................................................................7
4.1.1

Request..............................................................................................................................7

4.1.2

Request Parameters..........................................................................................................7

4.1.3

Response...........................................................................................................................8

4.1.4

Response Parameters.......................................................................................................8

Cancel Subscription to Zonal Presence Notifications.................................................................9


5.1.1

Request..............................................................................................................................9

5.1.2

Request Parameters .........................................................................................................9

5.1.3

Response...........................................................................................................................9

5.1.4

Response Parameters ......................................................................................................9

Zonal Presence Notification...........................................................................................................9

Query Zone List..............................................................................................................................11

7.1.1

Request............................................................................................................................11

7.1.2

Request Parameters........................................................................................................11

7.1.3

Response.........................................................................................................................11

7.1.4

Response Parameters.....................................................................................................11

Query Zone Status.........................................................................................................................12


8.1.1

Request............................................................................................................................12

8.1.2

Request Parameters........................................................................................................12

8.1.3

Response.........................................................................................................................12

8.1.4

Response Parameters.....................................................................................................12

Query a named set of Access Point Status................................................................................13


9.1.1

Request............................................................................................................................13

Page 3

Zonal Presence REST V1.0

10

11

12

13

14

Document Version: 1.1

9.1.2

Request Parameters........................................................................................................13

9.1.3

Response.........................................................................................................................13

9.1.4

Response Parameters.....................................................................................................14

Query all Access Point Status......................................................................................................14


10.1.1

Request............................................................................................................................14

10.1.2

Request Parameters........................................................................................................14

10.1.3

Response.........................................................................................................................14

10.1.4

Response Parameters.....................................................................................................15

Query a User within a Zone..........................................................................................................16


11.1.1

Request............................................................................................................................16

11.1.2

Request Parameters........................................................................................................16

11.1.3

Response.........................................................................................................................16

11.1.4

Response Parameters.....................................................................................................17

Query all Users on an Access Point............................................................................................17


12.1.1

Request............................................................................................................................17

12.1.2

Request Parameters........................................................................................................17

12.1.3

Response.........................................................................................................................17

12.1.4

Response Parameters.....................................................................................................18

Query all Users within a Zone......................................................................................................18


13.1.1

Request............................................................................................................................18

13.1.2

Request Parameters........................................................................................................18

13.1.3

Response.........................................................................................................................18

13.1.4

Response Parameters.....................................................................................................19

Response Codes & Exceptions....................................................................................................19

14.1 Response Codes..........................................................................................................................19


14.2

Exceptions...................................................................................................................................20
14.2.1

Service Exceptions..........................................................................................................20

14.2.2

Policy Exceptions.............................................................................................................20

Page 4

Zonal Presence REST V1.0

Document Version: 1.1

Zonal Presence REST Overview

The Zonal Presence interface allows a Web application to subscribe to notifications of when a mobile device
enters, exits or moves between access points within a zone. It can also query the status of users, access
points and zones.
When using this document you will also need to refer to the 'OneAPI V2.0 Common Information Guide' for
information on common data types.

Throughout this document, the examples may be shown WITHOUT URL encoding
for readability purposes.

Authentication

A server side certificate is required plus HTTP Basic Authentication.


For more information, refer to the ''Developer Access' section in the 'OneAPI V2.0 Common Information
Guide' available from http://oneapi.aepona.com.

Methods

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

Initiate Subscription to Zonal Presence Notifications

Cancel 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

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 Presence
API are as follows:

Page 5

Zonal Presence REST V1.0

3.1

Document Version: 1.1

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 notifications


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

Query to retrieve a list of zones the application is authorized to use


http://example.com/{api version}/zonalpresence/queries/zone

Query to retrieve the status of a zone and relevant statistics


http://example.com/{api version}/zonalpresence/queries/zoneStatus?zoneId={zoneId}

Query a named set of access point status in a zone


http://example.com/{api version}/zonalpresence/queries/accessPointStatus?
zoneId={zoneId}&accessPointId={accessPointId}

Query to retrieve the status of all access points in a zone


http://example.com/{api version}/zonalpresence/queries/accessPointStatus?
zoneId={zoneId}

Query to retrieve the status of a user within a zone


http://example.com/{api version}/zonalpresence/queries/userStatus?
zoneId={zoneId}&address={address}

Query to retrieve the status of all users within an access point


http://example.com/{api version}/zonalpresence/queries/userStatus?
zoneId={zoneId}&accessPointId={accessPointId}

Query to retrieve the status of all users within a zone


http://example.com/{api version}/zonalpresence/queries/userStatus?zoneId={zoneId}

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

Representation formats the response content type for the Zonal Presence API is
application/JSON.

Page 6

Zonal Presence REST V1.0

Document Version: 1.1

Initiate Subscription to Zonal Presence Notifications

This method allows the Web application to subscribe to zonal presence notifications.

4.1.1

Request

POST http://example.com/1/zonalpresence/subscriptions/yumscoffee HTTP/1.1


Host: example.com:80
Content-Type: application/json
Accept: application/json
{
zonePresenceSubscribe: {
callbackReference: {
notifyURL: http://www.yoururl.here/notification/,
callbackData: doSomething,
notificationFormat: XML
},
clientCorrelator: 12345
}
}

4.1.2

Request Parameters
Table 1: Subscribe to Zonal Presence Notifications Request Parameters

Parameter

Description

Optional

notifyURL

This is used by the server to POST the notifications

No

you; so include the URL of your own listener


application.
callbackData

Data the application can register with the server when

Yes

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 notifications, e.g. for correlation purposes.
notificationFormat

Default: XML

Yes

Application can specify format of the resource


representation in notifications that are related to this
subscription. The choice is between {XML, JSON}.
clientCorrelator

Uniquely identifies this create subscription request. If


there is communication failure during the request,
using the same clientCorrelator when retrying a
request allows the operator to avoid creating a

Page 7

Yes

Zonal Presence REST V1.0

Document Version: 1.1


duplicate subscription.

4.1.3

Response

HTTP/1.1 201 Created


Content-Type: application/json
Location: http://example.com/1/zonalpresence/subscriptions/yumscoffee/12345
Date: 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
}
}

4.1.4

Response Parameters

A '201' resource indicates the subscription has been created at the URL in the Location header. '12345'
indicates the subscriptionID that will be used when cancelling the subscription.

Table 2: Subscription of Zonal Presence Notifications Response Parameters


Parameter

Description

Optional

notifyURL

This is used by the server to POST the notifications

No

you; so include the URL of your own listener


application.
callbackData

Data the application can register with the server when

Yes

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 notifications, e.g. for correlation purposes.
notificationFormat

Default: XML

Yes

Application can specify format of the resource


representation in notifications that are related to this
subscription. The choice is between {XML, JSON}.

Page 8

Zonal Presence REST V1.0


clientCorrelator

Document Version: 1.1


Uniquely identifies this create subscription request. If

Yes

there is communication failure during the request,


using the same clientCorrelator when retrying a
request allows the operator to avoid creating a
duplicate subscription.
resourceURL

The URL that addresses the resource. Matches the

No

information in the Location header.

Cancel Subscription to Zonal Presence Notifications

This method allows the Web application to cancel the subscription to zonal presence notifications.

5.1.1

Request

DELETE http://example.com/1/zonalpresence/subscriptions/yumscoffee/12345 HTTP/1.1


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

5.1.2

Request Parameters

None

5.1.3

Response

HTTP/1.1 204 No Content


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

5.1.4

Response Parameters

None

Zonal Presence Notification

This is the notification that is sent to your application.


POST http://www.yoururl.here/notification/
Content-Type: application/json
Content-Length: 1234
{
zonePresenceNotification: {
callbackData: doSomething,
timestamp: 2011-02-01T12:00:00,
zoneId: yumscoffee,

Page 9

Zonal Presence REST V1.0

Document Version: 1.1

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
}
}
]
}
}

Table 3: Zonal Presence Notification Parameters


The JSON response is an object named zonalPresenceNotification. This contains the callbackData,

timestamp, zoneId, and at least one userEvent object, which is comprised of the following parameters:
Parameter

Description

Optional

timeStamp

Date and time of day of the event.

No

address

The identity of the user, either a MSISDN or

No

Anonymous Customer Reference (ACR)


userEvent

Can be one of the following:

zoneEnter which lists the currentAccessPoint


zoneExit which lists the currentAccessPoint
zoneTransfer which lists the
currentAccessPoint and previousAccessPoint

Page 10

No

Zonal Presence REST V1.0

Document Version: 1.1

Query Zone List

This method allows the Web application to query for all the zone identifiers it is authorized to use.

7.1.1

Request

GET http://example.com/1/zonalpresence/queries/zone HTTP/1.1


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

7.1.2

Request Parameters

None

7.1.3

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1024
Date: Thu 04, June 2009 02:51:59 GMT

{
zoneList: {
zone: [
{
zoneId: yumscoffee
},
{
zoneId: yumsmuseum
}
]
}
}

7.1.4

Response Parameters

The JSON response us an object named zoneList which may contain an object named zone, which in turn
contains at least one of the following:

Table 4: Query Zone List Response Parameters


Parameter

Description

Optional

zoneId

Unique identifier for the zone.

No

Page 11

Zonal Presence REST V1.0

Document Version: 1.1

Query Zone Status

This method allows the Web application to query a zone for it's status and other relevant information.

8.1.1

Request

GET http://example.com/1/zonalpresence/queries/zoneStatus?zoneId=yumscoffee HTTP/1.1


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

8.1.2

Request Parameters

The zoneId is passed as an attribute in the HTTP request.

8.1.3

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1024
Date: Thu 04, June 2009 02:51:59 GMT
{
zoneStatus: {
zoneId: yumscoffee,
numberOfUsers: 36,
numberOfAccessPoints: 12,
numberOfUnserviceableAccessPoints: 1
}
}
}

8.1.4

Response Parameters

The JSON response us an object named zoneStatus which contains the following:

Table 5: Query Zone List Response Parameters


Parameter

Description

Optional

zoneId

Unique identifier for the zone.

No

numberOfUsers

Number of users currently camped onto to the access

No

point within the zone.


numberOfAccessPoints

Number of access points within the zone.

Page 12

No

Zonal Presence REST V1.0


numberOfUnserviceableAccessPoi

Document Version: 1.1


Number of inoperable access points within the zone.

nts

Query a named set of Access Point Status

This method allows the Web application to query a named set of access point status.

9.1.1

Request

GET http://example.com/1/zonalpresence/queries/accessPointStatus?
zoneId=yumscoffee&accessPointId=femto01 HTTP/1.1
Host: example.com:80
Accept: application/json

9.1.2

Request Parameters

The zoneId and one or more accessPointId are passed as attributes in the HTTP request.

9.1.3

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-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,
accuracy: 10.0
}
}
]
}

Page 13

No

Zonal Presence REST V1.0

Document Version: 1.1

9.1.4

Response Parameters

The JSON response us an object named accessPointStatus which contains the following:

Table 6: Query Access Point Status Response Parameters


Parameter

Description

Optional

accessPointId

Unique identifier for the access point.

No

accessType

operationStatus

locationInfo

10

The access type. Can be one of the following:


- femto
- wifi
- pico
- marco
- wimax
The current state of the access point. Can be:
- Serviceable
- Unserviceable
The coordinates of the access point incuding:
- latitude
- longitude
- altitude
- accuracy
Note: if locationInfo is supplied, only latitude and
longitude are mandatory, altitude and accuracy are
optional.

No

No

Yes

Query all Access Point Status

This method allows the Web application to query all access point status'.

10.1.1 Request
GET http://example.com/1/zonalpresence/queries/accessPointStatus?zoneId=yumscoffee
HTTP/1.1
Host: example.com:80
Accept: application/json

10.1.2 Request Parameters


The zoneId is passed as an attribute in the HTTP request.

10.1.3 Response
HTTP/1.1 200 OK
Content-Type: application/json

Page 14

Zonal Presence REST V1.0

Document Version: 1.1

Content-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,
accuracy: 10.0
}
},
{
accessPointId: femto02,
accessType: femto,
numberOfUsers: 13,
operationStatus: SERVICEABLE,
locationInfo: {
longitude: -80.630554,
latitude: 44.677223,
altitude: 40.0,
accuracy: 10.0
}
}
]
}
}

10.1.4 Response Parameters


The JSON response us an object named accessPointStatus which contains the following:

Table 7: Query Access Point Status Response Parameters


Parameter

Description

Optional

accessPointId

Unique identifier for the access point.

No

accessType

The access type. Can be one of the following:

Page 15

No

Zonal Presence REST V1.0

operationStatus

locationInfo

11

Document Version: 1.1


- femto
- wifi
- pico
- marco
- wimax
The current state of the access point. Can be:
- Serviceable
- Unserviceable
The coordinates of the access point incuding:
- latitude
- longitude
- altitude
- accuracy
Note: if locationInfo is supplied, only latitude and
longitude are mandatory, altitude and accuracy are
optional.

Query a User within a Zone

This method allows the Web application to query one or more user(s) within a zone.

11.1.1 Request
GET http://example.com/1/zonalpresence/queries/userStatus?
zoneId=yumscoffee&address=tel:+16131234000 HTTP/1.1
Host: example.com:80
Accept: application/json

11.1.2 Request Parameters


The zoneId and one or more address are passed as attributes in the HTTP request.

11.1.3 Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1024
Date: Thu 04, June 2009 02:51:59 GMT

{
userStatusList: {
zoneId: yumscoffee,
userStatus: [
{
address: tel:+16131234000,
accessPointId : femto02
}
]

Page 16

No

Yes

Zonal Presence REST V1.0

Document Version: 1.1

}
}

11.1.4 Response Parameters


The JSON response us an object named userStatusList which contains a zoneId and a userStatus with the
following:

Table 8: Query User within a Zone Response Parameters


Parameter

Description

Optional

address

The identity of the user, either a MSISDN or

No

Anonymous Customer Reference (ACR).


accessPointID

12

Unique identifier for the access point.

Query all Users on an Access Point

This method allows the Web application to query all the users on an access point.

12.1.1 Request
GET http://example.com/1/zonalpresence/queries/userStatus?
zoneId=yumscoffee&accessPointId=femto02 HTTP/1.1
Host: example.com:80
Accept: application/json

12.1.2 Request Parameters


The zoneId and accessPointId are passed as attributes in the HTTP request.

12.1.3 Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1024
Date: Thu 04, June 2009 02:51:59 GMT

{
userStatusList: {
zoneId: yumscoffee,
userStatus: [
{
address: tel:+16131234000,
accessPointId : femto02

Page 17

No

Zonal Presence REST V1.0

Document Version: 1.1

},
{
address: tel:+16131235000,
accessPointId : femto02
}
]
}
}

12.1.4 Response Parameters


The JSON response us an object named userStatusList which contains a zoneId and a userStatus with the
following:

Table 9: Query Users on an Access Point Response Parameters


Parameter

Description

Optional

address

The identity of the user, either a MSISDN or

No

Anonymous Customer Reference (ACR).


accessPointID

13

Unique identifier for the access point.

No

Query all Users within a Zone

This method allows the Web application to query all the users within a zone.

13.1.1 Request
GET http://example.com/1/zonalpresence/queries/userStatus?zoneId=yumscoffee HTTP/1.1
Host: example.com:80
Accept: application/json

13.1.2 Request Parameters


The zoneId is passed as an attribute in the HTTP request.

13.1.3 Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1024
Date: Thu 04, June 2009 02:51:59 GMT

{
userStatusList: {

Page 18

Zonal Presence REST V1.0

Document Version: 1.1

zoneId: yumscoffee,
userStatus: [
{
address: tel:+16131234000,
accessPointId : femto02
},
{
address: tel:+16131235000,
accessPointId : femto02
},
{
address: tel:+16131234567,
accessPointId : femto01
}
]
}
}

13.1.4 Response Parameters


The JSON response us an object named userStatusList which contains a zoneId and a userStatus with the
following:

Table 10: Query Users on an Access Point Response Parameters


Parameter

Description

Optional

address

The identity of the user, either a MSISDN or

No

Anonymous Customer Reference (ACR).


accessPointID

14

Unique identifier for the access point.

No

Response Codes & Exceptions

14.1 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

Page 19

Zonal Presence REST V1.0

Document Version: 1.1

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.

14.2

Exceptions

HTTP/1.1 400

Bad Request

Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"requestError": {
"serviceError": {
"messageId": "SVC0002",
"text": " Invalid input value for message part %1",
"variables": " tel:+16309700000"
}
}

This section lists the available error codes, the possible reasons why the exception may have occurred, and
possible solutions.

14.2.1 Service Exceptions


The following service exceptions may be thrown:

Table 11: Service Exceptions


Error

Explanation

SVC0001 Service error occurred

A service-related error has occurred as a result of a client


invocation on the service. This category can be used for
implementation-specific errors. Contact the support team.

SVC0002 Invalid input value

An input parameter value is not of the expected type. Check


the parameter types and re-submit your request.

SVC0004 No valid address(es)

The requested terminal device address does not exist. Use an


address that exists.

14.2.2 Policy Exceptions


A policy exception means that the request syntax is valid, however an operator policy has been broken.
POL0001 - Policy error occurred

Page 20

Zonal Presence REST V1.0

Document Version: 1.1

The above exception may be thrown to indicate a fault relating to a policy associated with the service. This
category can be used for implementation-specific errors such as:

Table 12: Policy Error Codes


Error

Explanation

POL-006: TPA exceeded its

The maximum rate of transactions is exceeded. Ensure that

maximum allowed rate of

the rate of your requests is within the limits set up in your

transactions

SLA, e.g. 10 TPS (Transactions Per Second).

POL-008: TPA is invalid

The Third Party Application authentication details are


incorrect. Check your basic authentication username and
password are correct and re-submit your request.

POL-014: White List is enforced,

A white list is enforced and the number is not in the white list.

and address is not in White List

Check your SLA details.

POL-015: Black List is enforced,

A black list is enforced and the number is in the black list.

and address is in Black List

Check you SLA details.

POL-016: Max Requests is

The maximum number of requests for this service is

enforced, and max requests has

exceeded. Contact the support team.

been exceeded
POL-017: Operation is not allowed

The method/operation is not supported in your current SLA.


Check your SLA and use a method that is supported.

POL-040: Max Destination

A maximum destination address limit is enforced and it has

Addresses is enforced and

been exceeded. Check your SLA for the limit and re-submit

maximum destination addresses has

your request.

been exceeded

Page 21