Aepona V1 0 Femto Zonal Presence REST

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
8.1.3
Response.........................................................................................................................12
8.1.4
Query a named set of Access Point Status................................................................................13

9.1.1
Request............................................................................................................................13
Page 3
10
11
12
13
14
9.1.2
9.1.3
Response.........................................................................................................................13
9.1.4
Query all Access Point Status......................................................................................................14

10.1.1
Request............................................................................................................................14
10.1.2
10.1.3
Response.........................................................................................................................14
10.1.4
Query a User within a Zone..........................................................................................................16

11.1.1
Request............................................................................................................................16
11.1.2
11.1.3
Response.........................................................................................................................16
11.1.4
Query all Users on an Access Point............................................................................................17

12.1.1
Request............................................................................................................................17
12.1.2
12.1.3
Response.........................................................................................................................17
12.1.4
Query all Users within a Zone......................................................................................................18

13.1.1
Request............................................................................................................................18
13.1.2
13.1.3
Response.........................................................................................................................18
13.1.4
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 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
3.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
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

duplicate subscription.
4.1.3
Response
HTTP/1.1 201 Created

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

clientCorrelator

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

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/
{
zonePresenceNotification: {
timestamp: 2011-02-01T12:00:00,
zoneId: yumscoffee,
Page 9
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
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

7.1.2
Request Parameters
None
7.1.3
Response
HTTP/1.1 200 OK
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
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

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

numberOfUnserviceableAccessPoi

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
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
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
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
10.1.2 Request Parameters

10.1.3 Response
HTTP/1.1 200 OK
Page 14
Date: Thu 04, June 2009 02:51:59 GMT
{
accessPointStatusList: {
zoneId: yumscoffee,
accessPointStatus: [
{
accessType: femto,
numberOfUsers: 16,
locationInfo: {
altitude: 100.0,
accuracy: 10.0
}
},
{
accessType: femto,
numberOfUsers: 13,
locationInfo: {
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
No
accessType
The access type. Can be one of the following:
Page 15
No
operationStatus
locationInfo
11

- 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

The zoneId and one or more address are passed as attributes in the HTTP request.
11.1.3 Response
HTTP/1.1 200 OK
Date: Thu 04, June 2009 02:51:59 GMT
{
userStatusList: {
zoneId: yumscoffee,
userStatus: [
{
address: tel:+16131234000,
accessPointId : femto02
}
]
Page 16
No
Yes
}
}

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
No
Anonymous Customer Reference (ACR).

accessPointID
12
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

The zoneId and accessPointId are passed as attributes in the HTTP request.
12.1.3 Response
HTTP/1.1 200 OK
Date: Thu 04, June 2009 02:51:59 GMT
{
userStatusList: {
zoneId: yumscoffee,
userStatus: [
{
address: tel:+16131234000,
Page 17
No
},
{
address: tel:+16131235000,
}
]
}
}

following:
Table 9: Query Users on an Access Point Response Parameters

Parameter
Description
Optional
address
No

accessPointID
13
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

13.1.3 Response
HTTP/1.1 200 OK
Date: Thu 04, June 2009 02:51:59 GMT
{
userStatusList: {
Page 18
zoneId: yumscoffee,
userStatus: [
{
address: tel:+16131234000,
},
{
address: tel:+16131235000,
},
{
address: tel:+16131234567,
}
]
}
}

following:
Table 10: Query Users on an Access Point Response Parameters

Parameter
Description
Optional
address
No

accessPointID
14
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
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
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
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

Aepona V1 0 Femto Zonal Presence REST

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Aepona V1 0 Femto Zonal Presence REST

Hochgeladen von

Copyright:

Verfügbare Formate

UNIVERSAL SERVICE PLATFORM 3.

Zonal Presence REST V1.0

Document Version: 1.1

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

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

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

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

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

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

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

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

Zonal Presence REST V1.0

Document Version: 1.1

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

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

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

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

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

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

Zonal Presence REST V1.0

Document Version: 1.1

Zonal Presence REST Overview

A server side certificate is required plus HTTP Basic Authentication.

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

Zonal Presence REST V1.0

Document Version: 1.1

Cancel the subscription to zonal presence notifications

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

Query to retrieve the status of a zone and relevant statistics

Query a named set of access point status in a zone

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

Query to retrieve the status of a user within a zone

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

Query to retrieve the status of all users within a zone

Zonal Presence REST V1.0

Document Version: 1.1

Initiate Subscription to Zonal Presence Notifications

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

This is used by the server to POST the notifications

you; so include the URL of your own listener

Data the application can register with the server when

subscribing to notifications, and that are passed back

Application can specify format of the resource

Uniquely identifies this create subscription request. If

Zonal Presence REST V1.0

Document Version: 1.1

HTTP/1.1 201 Created

Table 2: Subscription of Zonal Presence Notifications Response Parameters

This is used by the server to POST the notifications

you; so include the URL of your own listener

Data the application can register with the server when

subscribing to notifications, and that are passed back

Application can specify format of the resource

Zonal Presence REST V1.0

Document Version: 1.1