Open API Project
Aepona v2.0 Consent REST
Document Version 1.2
Document Revision History
Rev #
Date
Description
1.0
July 29 2013
Initial version, based on Aepona TWS 3.4 Consent v2.0
API Guide doc v1.7.
1.1
Nov 1 2013
Updated URI and code examples, to match production
platform.
1.2
Nov 14 2013
Further updates to match updated production platform.
Developer Guide
Page 2
© Aepona 2013. All rights reserved.
Copyright
2013
© Aepona Limited,
Beacon House,
Clarendon Dock,
Belfast BT1 3BG
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 Limited’s 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.
Developer Guide
Page 3
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
Table of Contents
1
Consent REST Overview
2
Authentication
3
Methods and URI
4
Create Subscriber Consent
4.1
Request
4.1.1
Request Parameters
4.2
Response
5
Update Subscriber Consent
5.1
Request
5.1.1
Request Parameters
5.2
Response
6
Delete Subscriber Consent
6.1
Request
6.1.1
Request Parameters
6.2
Response
7
Request Subscriber Consent
7.1
Request
7.1.1
Request Parameters
7.2
Response
7.2.1
Response Parameters
8
Query Subscriber Consent
8.1
Request
8.1.1
Request Parameters
8.2
Response
8.2.1
Response Parameters
9
Consent Callback
9.1
Request
9.1.1
Request Parameters
Developer Guide
Page 4
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
9.2
Response
9.2.1
Response Parameters
10
Status Responses
11
Response Codes & Exceptions
11.1
Response Codes
11.2
Exceptions
11.2.1
Service Exceptions
11.2.2
Policy Exceptions
12
Sandbox Service
12.1
Create Consent
12.2
Update Consent
12.3
Delete Consent
12.4
Request Consent
12.5
Query Consent
13
HELP & INFO Message Support
13.1
Help & Info Policy
Developer Guide
Page 5
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
1
Consent REST Overview
The Consent interface allows an application to request the consent of a subscriber before
it can use various enablers to perform actions against that subscriber, e.g. to obtain the
subscribers location or send the subscriber an SMS or MMS. In addition the API allows
direct management of subscriber consent via the 'Deposit API' methods: create, update
and delete consent, that may be used when the application is trusted to manage consent,
e.g. via its own subscriber dialogue mechanism. Access to these methods for applications
will be dependent on operation set policies. Consent is managed at the application level.
Consent Callback is described in section 9.
A sandbox service is available. The scenarios are described in section 12.
!
Please note that throughout this document, the examples may be shown
WITHOUT URL encoding for readability purposes. For example, if the address tel:
+12345678900 is in the example, this should be encoded as tel%3A
%2B12345678900, where the character ':' is denoted by '%3A' and the
character '+' by '%2B'.
!
Data types indicated as XSD in parameter tables refer to the standard XSD type.
Relevant information may be obtained from
2
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'.
3
Methods and URI
Consent may only be accessed via the REST API (described in this document). The
following methods are available, with their respective resource URI:
· Create ('deposit') consent of a subscriber - HTTP POST command - section 4
Developer Guide
Page 6
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
· Update consent previously deposited via the create operation - HTTP PUT command -
section 5
address={address}&status={status}&expiryTime={expiryTime}
· Delete consent previously deposited via the create operation - HTTP DELETE
command - section 6
· Request the consent of a subscriber - HTTP POST command - section 7
· Query the status of the subscriber consent - HTTP GET command - section 8
!
The Consent API supports application/x-www-form-urlencoded for POST operations.
The response content type is application/XML.
4
Create Subscriber Consent
This method allows the application to 'deposit' consent that is managed by a mechanism
outside of TWS.
4.1
Request
Content-Type: application/x-www-form-urlencoded
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
Content-Length: 80
Host: developerportal.uscellular.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Developer Guide
Page 7
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
expiryTime=100&address=tel%3A
%2B12345600001&operation=createConsent&status=ALLOWED
!
Query strings should be URL encoded.
4.1.1 Request Parameters
Table 1: Create Subscriber Consent - Request Parameters
Parameter
Data Type
Description
Optional
address
xsd:anyURI
The address (CTN) of U.S. Cellular
No
subscriber, whose consent request is being
deposited, in the format comprising:
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for example,
tel:+15087300001
The address must be must be URL-escaped
where %3A represents ‘:’ and %2B
represents ‘+’.
Example: %3A%2B15087300001
operation
xsd:string
Must be 'createConsent' to distinguish from
No
the requestConsent POST method.
status
status
The consent status. (See table 9 for
No
details).
expiryTime
xsd:int
The number of hours until the consent
No
expires.
Developer Guide
Page 8
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
4.2
Response
HTTP/1.1 204 No Content
Date: Thu, 31 Oct 2013 16:17:25 GMT
Server: Jetty(6.1.x)
Content-Type: application/xml
Host: developerportal.uscellular.com
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
expiryTime: 100
operation: createConsent
breadcrumbId: ID-ase3-43542-1383117279982-14-10
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
address: tel:+12345600001
status: ALLOWED
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
5
Update Subscriber Consent
Allows the application to update consent previously deposited via the create operation.
5.1
Request
expiryTime=100&address=tel%3A%2B12345600001&status=DENIED HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
Content-Length: 0
Host: developerportal.uscellular.com
Connection: Keep-Alive
Developer Guide
Page 9
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
!
Query strings should be URL encoded.
5.1.1 Request Parameters
Table 2: Update Subscriber Consent - Request Parameters
Parameter
Data Type
Description
Optional
address
xsd:anyURI
The address (CTN) of U.S. Cellular
No
subscriber, whose consent is being
updated, in the format comprising:
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for
example, tel:+15087300001
The address must be must be URL-
escaped where %3A represents ‘:’ and
%2B represents ‘+’.
Example: %3A%2B15087300001
status
status
The consent status. (See table 9 for
No
details).
expiryTime
xsd:int
The number of hours until the consent
No
expires.
5.2
Response
HTTP/1.1 204 No Content
Date: Thu, 31 Oct 2013 16:22:25 GMT
Server: Jetty(6.1.x)
Developer Guide
Page 10
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
Content-Type: application/xml
Host: developerportal.uscellular.com
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
breadcrumbId: ID-ase2-51909-1383117280141-22-14
status: DENIED
expiryTime: 100
X-Forwarded-Server: developerportal.uscellular.com
address: tel:+12345600001
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
Content-Length: 0
Keep-Alive: timeout=5, max=99
Connection: Keep-Alive
6
Delete Subscriber Consent
Allows the application to delete consent previously deposited via the create operation.
6.1
Request
%2B12345600001 HTTP/1.1
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
Host: developerportal.uscellular.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
!
Query strings should be URL encoded.
Developer Guide
Page 11
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
6.1.1 Request Parameters
Table 3: Delete Subscriber Consent Request Parameters
Parameter
Data Type
Description
Optional
address
xsd:anyURI
The address (CTN) of U.S. Cellular
No
subscriber, the consent deposit for whom
is being deleted, in the format
comprising:
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for
example, tel:+15087300001
The address must be must be URL-
escaped where %3A represents ‘:’ and
%2B represents ‘+’.
Example: %3A%2B15087300001
6.2
Response
HTTP/1.1 204 No Content
Date: Thu, 31 Oct 2013 16:25:08 GMT
Server: Jetty(6.1.x)
Content-Type: application/xml
Host: developerportal.uscellular.com
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
address: tel:+12345600001
breadcrumbId: ID-ase3-43542-1383117279982-14-13
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Developer Guide
Page 12
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
7
Request Subscriber Consent
Allows the application to seek consent from a subscriber for various actions e.g. to access
their location or to be able to send an SMS to the subscriber.
7.1
Request
%2Fexample.com%2FMockRestService%2Frest&address=tel%3A%2B12345600001 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
!
Query strings should be URL encoded. The address parameter is converted to tel
%3A%2B12345600001 and the callback URL parameter is converted to http%3A
7.1.1 Request Parameters
Table 4: Request Subscriber Consent Request Parameters
Parameter
Data Type
Description
Optional
address
xsd:anyURI
The address (CTN) of U.S. Cellular
No
subscriber, whose consent is requested, in
the format comprising:
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for
example, tel:+15087300001
The address must be must be URL-escaped
where %3A represents ‘:’ and %2B
Developer Guide
Page 13
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
represents ‘+’.
Example: %3A%2B15087300001
operation
xsd:string
This parameter is used to distinguish this
Yes
operation from the createConsent
operation. It may be absent, or anything
other than 'createConsent'
callbackUrl
xsd:anyURI
The URL to be invoked when the subscriber
No
has given/withheld their consent.
7.2
Response
HTTP/1.1 200 OK
Date: Thu, 31 Oct 2013 16:25:08 GMT
Server: Jetty(6.1.x)
Content-Type: application/xml
Host: developerportal.uscellular.com
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Consent status="PENDING"/>
7.2.1 Response Parameters
Table 5: Request Subscriber Consent Response Parameters
Parameter
Data Type
Description
Optional
status
status
The consent status. (See table 9 for
No
details).
Developer Guide
Page 14
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
8
Query Subscriber Consent
Allows the application to query the response of a previous consent request.
8.1
Request
HTTP/1.1
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
!
Query strings should be URL encoded.
8.1.1 Request Parameters
Table 6: Query Subscriber Consent - Request Parameters
Parameter
Data Type
Description
Optional
address
xsd:anyURI
The address (CTN) of U.S. Cellular
No
subscriber, in the format comprising:
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for
example, tel:+15087300001
The address must be must be URL-
escaped where %3A represents ‘:’ and
%2B represents ‘+’.
Example: %3A%2B15087300001
Developer Guide
Page 15
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
8.2
Response
HTTP/1.1 200 OK
Date: Thu, 31 Oct 2013 16:25:08 GMT
Server: Jetty(6.1.x)
Content-Type: application/xml
Host: developerportal.uscellular.com
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Authorization: Basic QWVwb25hVfdghfdghdfghdfgWF6eHN3MjNl
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Consent status="PENDING"/>
8.2.1 Response Parameters
Table 7: Query Subscriber Consent - Response Parameters
Parameter
Data Type
Description
Optional
status
status
The consent status. (See table 9 for
No
details).
9
Consent Callback
When the subscriber gives their consent or withholds it, your service at the callback URL
(which you specified in your original consent request) is invoked. Your service must
respond with “204 No Content”.
9.1
Request
HTTP/1.1
Accept: application/xml
Content-type: application/xml
Developer Guide
Page 16
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
<?xml version="1.0" encoding="UTF-8"?>
<privacyReceipt>
<subscriber>tel:+15087300001</subscriber>
<status>ALLOWED</status>
</privacyReceipt>
9.1.1 Request Parameters
Table 8: Consent Callback - Request Parameters (consentEventType)
Parameter
Data Type
Description
Optional
subscriber
xsd:anyURI
The address (CTN) of U.S. Cellular
No
subscriber, in the format comprising:
1) 'tel:' protocol identifier,
2) country code of one preceded by '+',
3) ten digit CTN preceded by 1, for
example, tel:+15087300001
The address must be must be URL-
escaped where %3A represents ‘:’ and
%2B represents ‘+’.
Example: %3A%2B15087300001
status
status
Specifies if the subscriber has granted or
No
denied consent. (See table 9 for
details).
9.2
Response
204 No Content
Developer Guide
Page 17
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
9.2.1 Response Parameters
N/A
10
Status Responses
The following Consent Response statuses may be returned:
Table 9: Status Types
Status
Description
PENDING
The subscriber has been notified by text message that the application
wishes to use their number. They have not yet replied and the request has
not yet expired.
ALLOWED
The subscriber has replied to the notification text message and has chosen
to allow the application to use their number.
DENIED
The subscriber has replied to the notification text message and has chosen
not to allow the application to use their number.
EXPIRED
The subscriber has not replied to the notification text message, and the
time allowed for replying has passed or the Consent session has expired
11
Response Codes & Exceptions
11.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 to create
an SMS instead of a POST
Developer Guide
Page 18
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
·
500 - The server encountered an unexpected condition. It 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 .
11.2 Exceptions
HTTP/1.1 403 Forbidden
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error> A policy error occurred. Error code is POL-014: Destination White List is enforced and
address is not in Destination White List.</error>
This section lists the available error codes, the possible reasons why the exception may
have occurred, and possible solutions.
11.2.1
Service Exceptions
The following exceptions may be thrown when an operation fails:
Table 10: Service Error Codes
Error
Explanation
SVC0001 - Service error
A service-related error has occurred as a result of a
occurred
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
The requested terminal device address does not exist.
address(es)
Use an address that exists.
Developer Guide
Page 19
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
11.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
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 11: Policy Error Codes
Error
Explanation
POL-006: TPA exceeded its
The maximum rate of transactions is exceeded.
maximum allowed rate of
Ensure that the rate of your requests is within the
transactions
limits set up in your 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
A white list is enforced and the number is not in the
enforced, and address is not in
white list. Check your SLA details.
White List
POL-015: Black List is
A black list is enforced and the number is in the black
enforced, and address is in
list. Check you SLA details.
Black List
POL-016: Max Requests is
The maximum number of requests for this service is
enforced, and max requests
exceeded. Contact the support team.
has been exceeded
POL-017: Operation is not
The method/operation is not supported in your
allowed
current SLA. Check your SLA and use a method that
is supported.
Developer Guide
Page 20
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
12
Sandbox Service
The Consent service contains a sandbox for use in testing applications using consent,
available at https://developerportal.uscellular.com/services/PrivacySandbox/.
This currently uses built in responses and does not make use of the sandbox data
service.
The behaviour of the sandbox is covered in the following subsections.
12.1
Create Consent
Creates consent using the specified request parameters.
All statuses are expired and removed after 5 minutes.
12.2
Update Consent
Updates (existing) consent using the specified request parameters.
12.3
Delete Consent
Deletes (existing) consent using the specified request parameters.
12.4
Request Consent
All requests will return a PENDING status.
In production, this status would change to ALLOWED or DENIED depending on the
response from the subscriber. Please use the Create Consent and Update Consent
methods to view these response in Sandbox.
All statuses are expired and removed after 5 minutes.
12.5
Query Consent
This returns the current status according to the rules above for requesting consent.
All statuses are expired and removed after 5 minutes.
Developer Guide
Page 21
© Aepona 2013. All rights reserved.
Aepona v2.0 Consent REST
Document Version 1.2
If the requested subscriber does not have a consent state associated, a 'Consent Not
Found' error will be returned.
13
HELP & INFO Message Support
13.1
Help & Info Policy
An application can choose to support HELP & INFO messages from the subscriber or rely
on more generic HELP & INFO messages configured through the Consent service. To
support HELP & INFO messages an application must request the administrator to enable
the “Help Info Messages” Policy. If an application chooses to support HELP & INFO
messages and a HELP or INFO message is received from a subscriber an event will be
published to the original callbackUrl appended with a “/keyword”.
If the original callbackUrl was http://callbackUrl/appName . The HELP or INFO event will be
Accept: text/plain
Content-type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<privacyReceipt>
<subscriber>tel:+447990123456</subscriber>
<messageType>messageTypeHelp</messageType>
<message>HELP blah, blah, blah</message>
</privacyReceipt>
Developer Guide
Page 22
© Aepona 2013. All rights reserved.